Furthermore, I see no reasons to have SystemProperty, SystemProperties
are just properties with a special meaning to the parent object.
I think we should consider removing SystemProperty and have an attribute
on PropertiesDesc annotation that specify whether this PropertyBag is
system or not
what do you think ?
jerome
Kedar Mhaswade wrote:
> Property is more ubiquitous than SystemProperty.
>
> AFAIK, SystemProperty exists at Domain, Cluster, Config and Server
> alone. Do you think it makes any good having a separate Bag of
> SystemProperties for these 4?
>
> Thanks,
> Kedar
>
> Lloyd Chambers wrote:
>> Jerome et al,
>>
>> One question that arises: since we have Property and PropertyBag,
>> should there by SystemProperty (exists) and SystemPropertyBag
>> (doesn't yet exist)?
>>
>> Lloyd
>>
>>
>> On Oct 20, 2008, at 10:07 AM, Lloyd Chambers wrote:
>>
>>> Thanks Jerome. Comments inline.
>>>
>>> On Oct 17, 2008, at 9:58 PM, Jerome Dochez wrote:
>>>
>>>> I like it, some remarks :
>>>>
>>>> 1. why is the annotation placed at the class level, shouldn't the
>>>> field List<Property> be annotated instead
>>> Good idea. I can't think of any reason not to do this, except that
>>> it could annotate the wrong method I suppose.
>>>
>>>>
>>>> 2. doing field annotation would remove the need to
>>>> SystemPropertiesDesc since you would just annotate List<Property>
>>>> systemProperties
>>> Yes, this is true. We would need to then make an explicit
>>> assumption about the name of the method in order to find and
>>> distinguish the annotations.
>>>
>>>>
>>>> 3. for description(), I would encourage for some i18n where instead
>>>> of an english description, we could reference a
>>>> LocalString.properties element. This would allow us to generate
>>>> localized @Configured documentation.
>>> It's essentially javadoc-equivalent I was thinking, which is all
>>> English at present. But if we think it's something we would expose
>>> via the GUI (for example), then it could be I18N. Perhaps it can be
>>> both, description() and descriptionKey().
>>>
>>>>
>>>> 4. is this a pure documentation play or should we push runtime
>>>> enforcement ?
>>> I think at the very least that it would be very helpful to customers
>>> to see warning messages in the log file if unknown properties were
>>> added, for example a mis-spelled one. This is much better than
>>> something mysteriously not working. The warning could emit a list
>>> of all legal properties, which could be very helpful.
>>>
>>> And perhaps an enforce() flag could be added, so that a module
>>> implementor could choose to enforce rejection of unknown properties.
>>>
>>>>
>>>> 5. I would question the "required()" boolean, I think AFAIK, there
>>>> are no required properties and if there are, maybe we should move
>>>> them to real attribute or element.
>>> OK, I wasn't sure on this. I think there might be one or two cases
>>> that require a property, I forget which ones.
>>>
>>>
>>>>
>>>>
>>>> Lloyd Chambers wrote:
>>>>> Team,
>>>>>
>>>>> I just finished going through "Sun GlassFish Enterprise Server v3
>>>>> Prelude Administration Reference". It took a lot of "eyeball
>>>>> work" going through every page, and each and every interface--this
>>>>> is error prone and hard to maintain.
>>>>>
>>>>> Many properties and system properties are documented in the
>>>>> reference, yet none of them are documented in the @Configured
>>>>> interfaces--at all. This stands in stark contrast to attributes
>>>>> and elements, which are naturally javadoc'd.
>>>>>
>>>>> Several other issues come to mind for properties (eg <property>
>>>>> and <system-property>):
>>>>> - no formal mechanism to document the legal properties (except
>>>>> free-form javadoc comments, none there as yet);
>>>>> - impossible to validate property names or values;
>>>>> - cannot warn the user if an unknown or mis-spelled property is
>>>>> being used (eg "readerThreads" instead of "reader-threads");
>>>>> - documentation for public API is not possible; there is nothing
>>>>> to generate it from;
>>>>> - no way for dependent interfaces (eg AMX) to validate or provide
>>>>> metadata.
>>>>>
>>>>> --- PROPOSAL ---
>>>>>
>>>>> 1) Add annotations to describe the legal properties and system
>>>>> properties;
>>>>> 2) Add these annotations on all the @Configured interfaces which
>>>>> have properties;
>>>>> 3) Encourage developers to maintain the annotations.
>>>>>
>>>>> Below is an example of how this would work for @Configured
>>>>> HttpListener. One alternative would be to define a "sidecar" class
>>>>> that has "public static final String" variables for each property,
>>>>> and annotate each of those individually.
>>>>>
>>>>> Note that because there cannot be more than one annotation of a
>>>>> given type, a grouping annotation is used to allow annotations for
>>>>> every property. See annotation classes further below.
>>>>>
>>>>> @PropertiesDesc({
>>>>> @PropertyDesc(name="recycle-objects", defaultValue="true",
>>>>> dataType=Boolean.class),
>>>>> @PropertyDesc(name="reader-threads", defaultValue="0",
>>>>> dataType=NonNegativeInteger.class),
>>>>> @PropertyDesc(name="acceptor-queue-length", defaultValue="4096",
>>>>> dataType=NonNegativeInteger.class),
>>>>> @PropertyDesc(name="reader-queue-length", defaultValue="4096",
>>>>> dataType=NonNegativeInteger.class),
>>>>> @PropertyDesc(name="use-nio-direct-bytebuffer",
>>>>> defaultValue="false", dataType=Boolean.class),
>>>>> @PropertyDesc(name="authPassthroughEnabled",
>>>>> defaultValue="false", dataType=Boolean.class),
>>>>> @PropertyDesc(name="proxyHandler",
>>>>> defaultValue="com.sun.enterprise.web.ProxyHandlerImpl"),
>>>>> @PropertyDesc(name="proxiedProtocol", values={"ws/tcp", "http",
>>>>> "https", "tls"}),
>>>>> @PropertyDesc(name="bufferSize", defaultValue="4096",
>>>>> dataType=NonNegativeInteger.class),
>>>>> @PropertyDesc(name="connectionTimeout", defaultValue="30",
>>>>> dataType=NonNegativeInteger.class),
>>>>> @PropertyDesc(name="maxKeepAliveRequests", defaultValue="250",
>>>>> dataType=NonNegativeInteger.class),
>>>>> @PropertyDesc(name="traceEnabled", defaultValue="true",
>>>>> dataType=Boolean.class),
>>>>> @PropertyDesc(name="cometSupport", defaultValue="false",
>>>>> dataType=Boolean.class),
>>>>> @PropertyDesc(name="jkEnabled", defaultValue="false",
>>>>> dataType=Boolean.class),
>>>>> @PropertyDesc(name="compression", defaultValue="off",
>>>>> values={"off","on","force"}),
>>>>> @PropertyDesc(name="compressableMimeType",
>>>>> defaultValue="text/html, text/xml, text/plain"),
>>>>> @PropertyDesc(name="noCompressionUserAgents", defaultValue=""),
>>>>> @PropertyDesc(name="compressionSize",
>>>>> dataType=NonNegativeInteger.class),
>>>>> @PropertyDesc(name="minCompressionSize",
>>>>> dataType=NonNegativeInteger.class),
>>>>> @PropertyDesc(name="crlFile"),
>>>>> @PropertyDesc(name="trustAlgorithm", values="PKIX"),
>>>>> @PropertyDesc(name="trustMaxCertLength", defaultValue="5",
>>>>> dataType=Integer.class),
>>>>> @PropertyDesc(name="disableUploadTimeout", defaultValue="true",
>>>>> dataType=Boolean.class),
>>>>> @PropertyDesc(name="connectionUploadTimeout", defaultValue="5",
>>>>> dataType=NonNegativeInteger.class),
>>>>> @PropertyDesc(name="uriEncoding", defaultValue="UTF-8",
>>>>> values={"UTF-8"})
>>>>> })
>>>>>
>>>>> @AMXConfigInfo(
>>>>> amxInterfaceName="com.sun.appserv.management.config.HTTPListenerConfig")
>>>>>
>>>>> @Configured
>>>>> public interface HttpListener extends ConfigBeanProxy, Injectable,
>>>>> PropertyBag {
>>>>>
>>>>> ...
>>>>> }
>>>>>
>>>>> ---
>>>>>
>>>>> /**
>>>>> * Describes properties or system properties that might exist as
>>>>> sub-elements.
>>>>> */
>>>>> @Retention(RUNTIME)
>>>>> @Target({TYPE})
>>>>> public @interface PropertyDesc {
>>>>> /** name of the property */
>>>>> String name();
>>>>>
>>>>> /** default value of the property */
>>>>> String defaultValue() default "\u0000";
>>>>>
>>>>> /** freeform description */
>>>>> String description() default "\u0000";
>>>>>
>>>>> /** Indicates that this property is required (rare) */
>>>>> boolean required() default false;
>>>>>
>>>>> /** the DataType class, can be Class<? extends {_at_link DataType}>
>>>>> or String.class */
>>>>> Class dataType() default String.class;
>>>>>
>>>>> /** Possible values, might not be a complete list and/or there
>>>>> could be other alternatives
>>>>> such as specific numbers, variables, etc.
>>>>> */
>>>>> String[] values();
>>>>> }
>>>>>
>>>>>
>>>>> /**
>>>>> * Annotation that holds an array of {_at_link PropertyDesc} for
>>>>> system properties eg {_at_link SystemProperty}.
>>>>> * Needed because it's not otherwise possible to have more than one
>>>>> annotation of the same type.
>>>>> */
>>>>> @Retention(RUNTIME)
>>>>> @Target({TYPE,METHOD})
>>>>> public @interface SystemPropertiesDesc {
>>>>> /** name of the property */
>>>>> PropertyDesc[] value();
>>>>> }
>>>>>
>>>>> /**
>>>>> * Annotation that holds an array of {_at_link PropertyDesc} for
>>>>> properties eg {_at_link Property}.
>>>>> * Needed because it's not otherwise possible to have more than one
>>>>> annotation of the same type.
>>>>> */
>>>>> @Retention(RUNTIME)
>>>>> @Target({TYPE,METHOD})
>>>>> public @interface PropertiesDesc {
>>>>> /** name of the property */
>>>>> PropertyDesc[] value();
>>>>> }
>>>>>
>>>>>
>>>>>
>>>>>
>>>>> ..............................................
>>>>> Lloyd Chambers
>>>>> lloyd.chambers_at_sun.com
>>>>> GlassFish team, LSARC member
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>>
>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: admin-unsubscribe_at_glassfish.dev.java.net
>>>> For additional commands, e-mail: admin-help_at_glassfish.dev.java.net
>>>>
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: admin-unsubscribe_at_glassfish.dev.java.net
>>> For additional commands, e-mail: admin-help_at_glassfish.dev.java.net
>>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: admin-unsubscribe_at_glassfish.dev.java.net
>> For additional commands, e-mail: admin-help_at_glassfish.dev.java.net
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: admin-unsubscribe_at_glassfish.dev.java.net
> For additional commands, e-mail: admin-help_at_glassfish.dev.java.net
>