Jerome,
Yes, agreed if we maintain a separation of <property> and <system-
property>.
If we merge them, then each PropertyDesc would systemProperty().
Maybe I misunderstood your intent...
Lloyd
On Oct 21, 2008, at 10:01 AM, Jerome Dochez wrote:
> Lloyd Chambers wrote:
>> Jerome,
>>
>> 1. On the annotation, yes we agreed on this yesterday when we
>> talked. I'll add systemProperty(), and remove required():
> I was thinking to have systemProperty() on the PropertiesDesc
> annotation, since you could group all the system properties
> together. Do we need such a fine grain level of control ?
>
> jerome
>>
>> @Retention(RUNTIME)
>> @Target({TYPE})
>> @Documented
>> public @interface PropertyDesc {
>> /** name of the property */
>> String name();
>>
>> /** default value of the property */
>> String defaultValue() default "\u0000";
>>
>> /** freeform description */
>> String description() default "\u0000";
>>
>> /** the DataType class, can be Class<? extends {_at_link
>> DataType}> or String.class, Integer.class, etc */
>> 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();
>>
>> /** returns true if this is a <system-property> */
>> boolean systemProperty();
>> }
>>
>>
>> Lloyd
>>
>> On Oct 20, 2008, at 9:29 PM, Jerome Dochez wrote:
>>
>>> 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
>>>>
>>>
>>>
>>> ---------------------------------------------------------------------
>>> 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
>