On 10/23/2011 1:15 PM, Pete Muir wrote:
> Sorry for the delay on this, I thought my messages were getting through but on talking to Linda, it appears they never arrived ;-)
>
> Hi Linda et al,
>
> I've collected some feedback internally at Red Hat/JBoss. The general consensus was that:
>
> * that adding the ability to configure more resources inside deployments is definitely something we should do
> * in general people prefer XML or fluent, programmatic API for config over annotations, but there is a significant minority who like annotations
> * however, no one thought annotations for configuration were a bad thing
> * that we, without question prefer the typed version of both the annotation and the XML over the properties version
> * that there are concerns that the obeying the annotation/xml attributes is too optional for vendors right now
>
> Regarding where to place the XML file, I wonder why the application.xml file / web.xml files cannot be reused - we already have a proliferation of config files, and it's quite important to not add to this, as it further steepens the initial learning curve.
+1.
>
> Further regarding your multi-tennant questions:
>
> * annotation based configuration of what may be modified is very ugly and I don't think we have an acceptable proposal there yet
> * XML based config looks good
>
> Finally, have you considered a programmatic, fluent API used to configure resources? We've found these to be very popular with users.
+1.
>
> On 26 Aug 2011, at 02:13, Linda DeMichiel wrote:
>
>> Aside from Reza's email (thanks, Reza!), we haven't received much
>> feedback on the resource configuration front. Under the assumption
>> that silence implies consent, we'd like to move on to the next steps
>> in this direction.
>>
>> This email contains a number of items that require your input.
>> Briefly, we need feedback on the following aspects:
>>
>> 1. The use of annotations for resource configuration.
>> 2. The form that such annotations (if supported) should take.
>> 3. The form of XML elements for resource configuration.
>> 4. How metadata related to per-tenant (re)configurability should be
>> specified.
>> 5. Whether the XML elements should be embedded in the current descriptors
>> or there should be a separate descriptor.
>>
>> These items are discussed further in the message below. I have
>> flagged specific items on which we need your feedback as "ISSUE:"
>>
>> Since the decision on how to specify metadata for reconfigurability
>> may likely impact the decision on the format to use to specify
>> annotations and XML for resource configuration, I recommend that you
>> make 2 passes to work through this:
>> (1) to review the options and how they interact;
>> (2) to provide your opinions on the issues.
>>
>> thanks,
>>
>> -Linda
>>
>> ---------------------------
>>
>> 1. Annotations for resource configuration
>>
>> Java EE 6 currently supports use of the DataSourceDefinition annotation.
>> This annotation is defined as follows:
>>
>> package javax.annotation.sql;
>>
>> @Retention(RUNTIME)
>> @Target({TYPE})
>> public @interface DataSourceDefinition {
>> String name();
>> String className();
>> String description() default "";
>> String url() default "";
>> String user() default "";
>> String password() default "";
>> String databaseName() default "";
>> int portNumber() default -1;
>> String serverName() default "localhost";
>> int isolationLevel() default -1;
>> boolean transactional() default true;
>> int initialPoolSize() default -1;
>> int maxPoolSize() default -1;
>> int minPoolSize() default -1;
>> int maxIdleTime() default -1;
>> int maxStatements() default -1;
>> String[] properties() default {};
>> int loginTimeout() default 0;
>> }
>>
>>
>> Following this pattern, we might define similar annotations for the other
>> standard resource types -- e.g., define JMSConnectionFactory, JMSDestination,
>> MailSession, and ConnectorResource annotations.
>>
>>
>> An alternative is to take a more generic approach, and instead of
>> these support a generic ResourceDefinition annotation:
>>
>> package javax.annotation.resource;
>>
>> @Retention(RUNTIME)
>> @Target({TYPE})
>> public @interface ResourceDefinition {
>> String description() default "";
>> String name();
>> String className();
>> String[] properties() default {};
>> }
>>
>> With the generic ResourceDefinition approach, all resource-specific
>> information would be provided as properties. For that reason, the generic
>> approach relies heavily on the use of strings and therefore has less
>> type safety. We would need to standardize on the property names to be
>> used, and we would also need to decide whether to require a
>> package-specific prefix on the property names (as illustrated in the
>> examples below) to distinguish them from vendor properties.
>>
>>
>> Examples:
>>
>> Example 1: data sources
>>
>> @DataSourceDefinition(
>> name="java:app/MyDataSource",
>> className="com.foobar.MyDataSource",
>> portNumber=6689,
>> serverName="myserver.com",
>> user="lance",
>> password="secret"
>> )
>>
>> vs
>>
>> @ResourceDefinition(
>> name="java:app/MyDataSource",
>> className="com.foobar.MyDataSource",
>> properties={
>> "javax.sql.portNumber=6689",
>> "javax.sql.serverName=myserver.com",
>> "javax.sql.user=lance",
>> "javax.sql.password=secret"
>> }
>> )
>>
>>
>> Example 2: JMS connection factories
>>
>> @JMSConnectionFactory(
>> name="java:app/MyJMSFactory",
>> resourceType="javax.jms.QueueConnectionFactory",
>> clientId="foo",
>> connectionTimeout=10,
>> initialPoolSize=5,
>> maxPoolSize=15
>> )
>>
>> vs
>>
>> @ResourceDefinition(
>> name="java:app/MyJMSFactory",
>> className="javax.jms.QueueConnectionFactory",
>> properties={
>> "javax.jms.clientId=foo",
>> "javax.jms.connectionTimeout=10",
>> "javax.jms.initialPoolSize=5",
>> "javax.jms.maxPoolSize=15"
>> }
>> )
>>
>>
>> Example 3: JMS destinations
>>
>> @JMSDestination(
>> name="java:app/MyQueue",
>> resourceType="javax.jms.Queue",
>> resourceName="queue124"
>> )
>>
>> vs
>>
>> @ResourceDefinition(
>> name="java:app/MyQueue",
>> className="javax.jms.Queue",
>> properties={
>> "javax.jms.resourceName=queue124"
>> }
>> )
>>
>>
>> ISSUE 1: Should we support the use of annotations for resource configuration
>> (in addition to DataSourceDefinition) or should we require that resource
>> configurability metadata be specified in XML?
>>
>> ISSUE 2: If we support the use of annotations, which of the above
>> approaches should we take -- resource-specific or generic?
>>
>> ISSUE 3: How should we name the standard properties? Do they require
>> a "package"-specific prefix?
>>
>> ISSUE 4: If we take a generic approach, should we use this for
>> DataSourceDefinition as well, treating the existing DataSourceDefinition
>> annotation and XML as "legacy"?
>>
>>
>> ------------------
>>
>>
>> 2. XML for resource configuration
>>
>> We currently support the use of the data-source element in the Java EE 6
>> descriptors as part of the jndiEnvironmentRefsGroup type. (See
>> http://java.sun.com/xml/ns/javaee/javaee_6.xsd for the details.)
>>
>> For the new elements, the choices are again whether to have elements
>> that are resource-specific or generic.
>>
>>
>> Example:
>>
>> Resource-specific approach, JMS connection factory:
>>
>> <jms-connection-factory>
>> <name>MyJMSFactory</name>
>> <resource-type>javax.jms.QueueConnectionFactory</resource-type>
>> <client-id>foo</client-id>
>> <connection-timeout>10</connection-timeout>
>> <initial-pool-size>5</initial-pool-size>
>> <max-pool-size>15</max-pool-size>
>> </jms-connection-factory>
>>
>>
>> Generic approach:
>>
>> <resource-definition>
>> <name>MyJMSFactory</name>
>> <resource-type>javax.jms.QueueConnectionFactory</resource-type>
>> <property>
>> <name>clientId</name>
>> <value>foo</value>
>> </property>
>> <property>
>> <name>connectionTimeout</name>
>> <value>10</value>
>> </property>
>> <property>
>> <name>initialPoolSize</name>
>> <value>5</value>
>> </property>
>> <property>
>> <name>maxPoolSize</name>
>> <value>15</value>
>> </property>
>> </resource-definition>
>>
>>
>> Note that the specification of properties could be made somewhat less
>> verbose by the use of attributes. The example above uses elements
>> to be more consistent with the current style of our deployment
>> descriptors.
>>
>>
>> With XML, we again have the issue as to whether properties in the
>> generic approach should use a resource-specific prefix, e.g.,
>>
>> <resource-definition>
>> <name>MyJMSFactory</name>
>> <resource-type>javax.jms.QueueConnectionFactory</resource-type>
>> <property>
>> <name>javax.jms.clientId</name>
>> <value>foo</value>
>> </property>
>> <property>
>> <name>javax.jms.connectionTimeout</name>
>> <value>10</value>
>> </property>
>> <property>
>> <name>javax.jms.initialPoolSize</name>
>> <value>5</value>
>> </property>
>> <property>
>> <name>javax.jms.maxPoolSize</name>
>> <value>15</value>
>> </property>
>> </resource-definition>
>>
>>
>> ISSUE 5: Which XML format should we use? Resource-specific or generic ?
>>
>>
>> ----------------------------
>>
>>
>> 3. Specification of per-tenant reconfigurability
>>
>> In the resource configuration document that I circulated several weeks
>> ago, I noted that we needed a means to include information about which
>> attributes of a resource definition must be modified by a tenant, which
>> must not be modified, and which may be modified.
>>
>> The remainder of this message outlines how that might be handled in
>> the various approaches.
>>
>> If we take a generic approach (@ResourceDefinition), the property elements
>> could be expanded to specify a configurability element. For example:
>>
>> @Retention(RUNTIME)
>> @Target({TYPE})
>> public @interface ResourceDefinition {
>> String description() default "";
>> String name();
>> String className();
>> ConfigProperty[] configProperties() default {};
>> }
>>
>> @Retention(RUNTIME)
>> @Target({})
>> public @interface ConfigProperty {
>> String name();
>> String value();
>> Configurability configurability() default Configurability.MAY_MODIFY;
>> }
>>
>> public enum Configurability {
>> MUST_MODIFY,
>> MUST_NOT_MODIFY,
>> MAY_MODIFY,
>> }
>>
>>
>>
>> Example:
>>
>> @ResourceDefinition(
>> name="java:app/MyJMSFactory",
>> className="javax.jms.QueueConnectionFactory",
>> configProperties={
>> @ConfigProperty(
>> name="clientId",
>> value="foo",
>> configurability=MUST_MODIFY),
>> @ConfigProperty(
>> name="connectionTimeout",
>> value="10"),
>> @ConfigProperty(
>> name="initialPoolSize",
>> value="5"),
>> @ConfigProperty(
>> name="maxPoolSize",
>> value="15")
>> }
>> )
>>
>>
>> A possible alternative to the use of the embedded @ConfigProperty
>> annotation approach might be to embed further syntax into the property
>> specification to capture configurabilty semantics. For example:
>>
>> @ResourceDefinition(
>> name="java:app/MyJMSFactory",
>> className="javax.jms.QueueConnectionFactory",
>> properties={
>> "javax.jms.clientId=foo", // must modify
>> "javax.jms.connectionTimeout=?10", // may modify
>> "javax.jms.transactional==true" // must not modify
>> }
>> )
>>
>>
>>
>> Things get more complicated with the typed resource definition
>> approach. Consider what happens to JMSConnectionFactory, where some
>> of the non-property elements are optional.
>>
>> Maintaining typing using the separate elements approach leads to
>> a proliferation of annotations.
>>
>> For example:
>>
>> @JMSConnectionFactory(
>> name="java:app/MyJMSFactory",
>> resourceType="javax.jms.QueueConnectionFactory",
>> clientId=_at_ClientId(value="foo",
>> configurability=Configurability.MUST_MODIFY),
>> connectionTimeout=_at_ConnectionTimeout(10),
>> initialPoolSize=_at_PoolSize(5),
>> maxPoolSize=_at_PoolSize(15)
>> )
>>
>>
>> An alternative is that only string-valued elements are used, and all
>> elements are of type ResourceElement:
>>
>> @Retention(RUNTIME) @Target({})
>> public @interface ResourceElement {
>> String value();
>> Configurability configurability() default Configurability.MAY_MODIFY;
>> }
>>
>>
>> Example:
>>
>> @JMSConnectionFactory(
>> name="java:app/MyJMSFactory",
>> resourceType="javax.jms.QueueConnectionFactory",
>> clientId=_at_ResourceElement(value="foo", configurability=MUST_MODIFY),
>> connectionTimeout=_at_ResourceElement("10"),
>> initialPoolSize=_at_ResourceElement("5"),
>> maxPoolSize=_at_ResourceElement("15")
>> )
>>
>>
>> ISSUE 6: Should we support the use of annotations for the specification
>> of per-tenant reconfigurability?
>>
>> ISSUE 7: If we support the use of annotations for the specification of
>> per-tenant reconfigurability, which approach should we take:
>> (1) Generic ResourceDefinition annotation
>> (2) Resource-specific annotations, using separate typed elements
>> (3) Resource-specific annotations, using ResourceElement approach
>> (4) Other?
>>
>>
>> ---------------------------
>>
>>
>> 4. Specification of per-tenant reconfigurability using XML
>>
>> With XML on the other hand, extension is fairly straightforward. The
>> various types could be augmented with attributes.
>>
>>
>> Example:
>>
>> <jms-connection-factory>
>> <name configurability=MUST_NOT_MODIFY>java:app/MyJMSFactory</name>
>> <resource-type configurability=MUST_NOT_MODIFY>
>> javax.jms.QueueConnectionFactory
>> </resource-type>
>> <client-id configurability=MUST_MODIFY>foo</client-id>
>> <connection-timeout>10</connection-timeout>
>> <initial-pool-size>5</initial-pool-size>
>> <max-pool-size>15</max-pool-size>
>> </jms-connection-factory>
>>
>>
>>
>> With the generic approach, this would look as follows, assuming
>> again a default of MAY_MODIFY if no attribute is specified:
>>
>> <resource-definition>
>> <name configurability=MUST_NOT_MODIFY>java:app/MyJMSFactory</name>
>> <resource-type configurability=MUST_NOT_MODIFY>
>> javax.jms.QueueConnectionFactory
>> </resource-type>
>> <property configurability=MUST_MODIFY>
>> <name>clientId</name>
>> <value>foo</value>
>> </property>
>> <property>
>> <name>connectionTimeout</name>
>> <value>10</value>
>> </property>
>> <property>
>> <name>initialPoolSize</name>
>> <value>5</value>
>> </property>
>> <property>
>> <name>maxPoolSize</name>
>> <value>15</value>
>> </property>
>> </resource-definition>
>>
>>
>> ISSUE 8: Which approach should we take for the specification of
>> per-tenant reconfigurability using XML: type-specific XML elements
>> or generic resource-definition elements?
>>
>>
>> ---------------------------------------
>>
>> 5. XML Descriptors for the specification of resource configuration.
>>
>> A further item pertains to where the XML elements for resource
>> configuration should be located -- i.e., in the existing Java EE
>> descriptors, or in a separate resources.xml (or services.xml)
>> descriptor. In our view, the fact that these resource configuration
>> elements are applicable to the application as a whole argues that there
>> should be a separate descriptor.
>>
>> ISSUE 9: Should resource configuration definitions be embedded in
>> the existing descriptors or should there be a separate XML descriptor?
>>
>> ---------------------------
>>
>>
>> RECAP OF THE ISSUES. ALL OF THESE NEED YOUR INPUT:
>>
>>
>> ISSUE 1: Should we support the use of annotations for resource configuration
>> (in addition to DataSourceDefinition) or should we require that resource
>> configurability metadata be specified in XML?
>>
>> ISSUE 2: If we support the use of annotation, which of the above
>> approaches should we take -- resource-specific or generic?
>>
>> ISSUE 3: How should we name the standard properties? Do they require
>> a "package"-specific prefix?
>>
>> ISSUE 4: If we take a generic approach, should we use this for
>> DataSourceDefinition as well, treating the existing DataSourceDefinition
>> annotation and XML as "legacy"?
>>
>> ISSUE 5: Which XML format should we use? Resource-specific or generic ?
>>
>> ISSUE 6: Should we support the use of annotations for the specification
>> of per-tenant reconfigurability?
>>
>> ISSUE 7: If we support the use of annotations for the specification of
>> per-tenant reconfigurability, which approach should we take:
>> (1) Generic ResourceDefinition annotation
>> (2) Resource-specific annotations, using separate typed elements
>> (3) Resource-specific annotations, using ResourceElement approach
>> (4) Other?
>>
>> ISSUE 8: Which approach should we take for the specification of
>> per-tenant reconfigurability using XML: type-specific XML elements
>> or generic resource-definition elements?
>>
>> ISSUE 9: Should resource configuration definitions be embedded in
>> the existing descriptors or should there be a separate XML descriptor?
>>
>> --------
>>
>> Thanks in advance for your feedback!
>>
>> -Linda
>>
>>
>
>
>
> -----
> No virus found in this message.
> Checked by AVG - www.avg.com
> Version: 2012.0.1831 / Virus Database: 2092/4567 - Release Date: 10/22/11
>
>
>