Date: Thu, 1 Sep 2011 15:06:07 +0200
Reza,
Thanks a lot for your suggestions or questions.
I'll add some remarks inline below. A general question is, whether you have
proposals for some or the items, e.g. naming or structure and definitions,
or prefer a joint effort by the EG on that?
On Tue, Aug 30, 2011 at 8:46 PM, Reza Rahman <reza_rahman_at_lycos.com> 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.
>
>
We have seen a shift towards annotations with Java EE 6, but a major problem
in real world environments is, that you cannot recompile your classes with
embedded annotations if XML was completely abandoned in a project. Of
course, using DI/CDI one could define environment specific code, and should
Java ever get to real modularity and dynamic loading (some EE servers do,
mostly thanks to OSGi [?]) such modules could be dynamically used at runtime,
too.
Until then, it seems, XML should also remain as configuration alternative,
especially in larger deployments or in a multi-tenancy scenario.
>
> * 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.
>
>
The case of annotations or enums being very generic came up with e.g. the
introduction of "ProjectStage" to JSF 2. This was a nice attempt, but for
real application lifecycles this is hardly ever sufficient. Not to mention,
each project or "tenant" may have its own naming scheme for each of those.
> * 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.
>
>
At the moment most descriptors are meant to be either inside a WAR or EAR.
As opposed to that, specific servers like Tomcat have its own xml
descriptors for data sources or similar (JNDI) configuration. Such as
context.xml which may reside inside the Web application overriding the
server's default. While e.g. Oracle WebLogic has a central file called
config.xml in each domain, plus a number of supporting XML files. While the
concept of a "domain" is the same, Glassfish calls its most central XML file
"domain.xml"
Rarely any of these are covered by current Java EE XML descriptors. While
files like "web.xml" or parts of the application may refer to a data source
or similar JNDI artifact, the actual definition of these artifacts is mostly
proprietary and not yet standardized.
There I don't think the existing files are sufficient. And most importantly
those that specify resources for each stage, environment or tenant must
remain independant of deliverables like a WAR or EAR.
> Hope this makes sense.
>
>
Same from me.
> Cheers,
> Reza
>
>
>
Werner
>
> 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> 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: 10.0.1392 / Virus Database: 1520/3855 - Release Date: 08/24/11
>
>
>
>
-- Werner Keil | UOMo Lead | Eclipse.org Twitter @wernerkeil | Skype: werner.keil | www.eclipse.org/uomo | #EclipseUOMo * JavaOne: October 2-6 2011, San Francisco, USA. Werner Keil, Agile Coach, UOMo Lead will co-present "JSR 321: Trusted Java API"
(image/gif attachment: 347.gif)