Reza,
Thanks very much for the thoughtful and detailed feedback.
I'm going to hold off commenting further for now -- because I want
a dialogue from the group, not myself.
Folks, could the rest of you please weigh in on all the issues!
thanks,
-Linda
On 8/30/2011 11:46 AM, Reza Rahman wrote:
> Linda,
>
> Overall, this looks good and is a timely change (I do have some concerns though). Detailed feedback below:
>
> * 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?
> - The annotations should definitely be supported. Although a majority of production applications are unlikely to use
> annotations for resource configuration, they are very valuable for RoR style RAD development and minimizing XML.
>
> * ISSUE 2: If we support the use of annotations, which of the above approaches should we take -- resource-specific or
> generic?
> - The generic annotation approach is very tempting, but does have some significant problems. Besides being less
> type-safe, they are also not very self-contained/self-documenting and hence much less usable. They could have been
> workable if the different resource types had more in common, but they really don't (besides some superficial
> similarities in properly names). I think we should avoid the generic annotation approach or reserve it for cases where
> containers use them to allow for configuring resources outside the common types. If we do have a generic annotation for
> edge cases, it is probably best to coordinate with an active JCA EG on that annotation since most if not all resources
> configured this way are likely to be JCA resources.
>
> * ISSUE 3: How should we name the standard properties? Do they require a "package"-specific prefix?
> - If we retain the generic annotation approach for provider-specific edge cases, we should recommend that properties use
> sensible "package"-specific prefixes. The issue is that although property names might be similar, their meaning and
> usage patterns would likely be very different depending on the actual resource type, so they should be categorized and
> documented separately.
>
> * 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"?
> - I think it was done right in Java EE 6 in the first place. For example, Resin has always had cleanly separated XML
> tags for database, JMS, etc resource configuration.
>
> * ISSUE 5: Which XML format should we use? Resource-specific or generic?
> - Resource specific for "well known" resources and generic for the others that would be provider specific with some
> usage guidelines.
>
> * ISSUE 6: Should we support the use of annotations for the specification of per-tenant reconfigurability?
> - As you know, I (and others) expressed concerns around cloud support in the past. I think this issue crystallizes some
> of those concerns. What I see as largely an edge case (multi-tenant Java EE applications that require a tenant-specific
> override) would complicate a far more mundane/common use case (deploying a resource in a vanilla Java EE application). I
> think we should reconsider if this particular cloud feature is really needed. If it is not, we could avoid this bit of
> complexity altogether. Multi-tenant enabled application developers would simply have to let deployers know what
> resources need to be overriden via more traditional forms of documentation without any container intervention (something
> they would likely need to do anyway). If we still think this is something that is really needed, it should be supported
> in annotations as well as XML. Having something in XML and not in annotations (or vice versa) is likely to be confusing.
>
> * ISSUE 7: If we support the use of annotations for the specification of per-tenant reconfigurability, which approach
> should we take.
> - If this feature is indeed needed, I think using resource-specific annotations with separate typed elements is the
> least worst. It is the most type-safe and self-documenting, but it will cause annotation bloat. All these options cause
> additional complexity for resource configuration in non-cloud applications. I could not think of an alternate way that
> avoids the complexity while still supporting this feature.
>
> * 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?
> - As stated above, type-specific elements are far more readable/self-documenting and less verbose (even more so in XML
> than in annotations).
>
> ISSUE 9: Should resource configuration definitions be embedded in the existing descriptors or should there be a separate
> XML descriptor?
> - I think the decision in Java EE 6 to utilize the existing descriptors is the correct one. It avoids adding yet another
> Java EE deployment descriptor instead of just putting resource definitions in application.xml, web.xml, beans.xml, etc.
> Resin has done application-specific resource deployment for ages and we've never seen a need to create a separate
> descriptor for resources. Similarly, Spring allows for resource definition in it's application context descriptors. I
> think creating a separate descriptor adds little value and goes against the norm for server-side Java development.
>
> Hope this makes sense.
>
> Cheers,
> Reza
>
>
> On 8/26/2011 11:34 AM, Reza Rahman wrote:
>> Linda,
>>
>> Hmm - for some reason I did not get your original email? I'm a bit tied up at the moment but will try to get you
>> detailed feedback by next week at the latest...
>>
>> Cheers,
>> Reza
>>
>>
>> On 8/26/2011 5:36 AM, Werner Keil wrote:
>>> Linda/all,
>>>
>>> Thanks a lot for the suggestions.
>>>
>>> I highly appreciate some of these items, especially JMS which I saw recently in a project can be a beast hard to
>>> tame. In fact, based on Oracle's (pre EE6) own technologies combined with some Spring which caused many issues, not
>>> only due to lack of understanding how to use it properly.
>>>
>>> I'll try to look into those, probably gather feedback from people who deal with this and reply here, particularly for
>>> the JMS Use Case, although it may not be the only one. Is this coordinated with JMS 2.0 btw, e.g. by having the Spec
>>> Lead on this list?
>>>
>>> Regards,
>>> Werner
>>>
>>> On Fri, Aug 26, 2011 at 3:13 AM, Linda DeMichiel <linda.demichiel_at_oracle.com <mailto:linda.demichiel_at_oracle.com>> 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 <http://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 <http://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 <http://www.avg.com>
>>> Version: 10.0.1392 / Virus Database: 1520/3855 - Release Date: 08/24/11
>>>
>>
>