Jerome,
1. Are you proposing to eliminate <system-property>? We discussed
this, and I like the idea.
Some items have *both* system properties and regular properties eg
Domain, Server, Config, Cluster.
So we might want to add a "system" attribute on <property>:
<property name="prop1" value="value1" description="..." system="true">
<property name="prop2" value="value2" description="..." system="false">
While the annotation will have systemProperty(), it's awkward to have
to get the annotation to distinguish a Property's type. We might
might to generalize this to type="system"|"normal"|"private"|whatever?
Lloyd
..............................................
Lloyd Chambers
lloyd.chambers_at_sun.com
GlassFish team, LSARC member
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
>