Sorry for the delay on this, I thought my messages were getting through but on talking to Linda, it appears they never arrived ;-)
I would agree with Reza. We should just support the configurability options in XML.
On 10 Sep 2011, at 01:10, Reza Rahman wrote:
> Linda,
>
> This does not change my initial opinion. I like the type-safe approach but question whether the configurability options are useful at all or are complicating life in a non-cloud deployment to support a cloud edge case. The configurability options also pose a backwards compatibility challenge with the existing data source annotations.
>
> Sorry I cannot be more supportive of the cloud features in this particular case. My position has always been that we should add cloud support while giving higher priority to non-cloud usage and preserving usability.
>
> Cheers,
> Reza
>
>
> On 9/9/2011 2:46 PM, Linda DeMichiel wrote:
>> I appreciate all the members who have weighed in on these issues so far.
>>
>> Since the responses have indicated a preference for the resource-specific
>> over the generic metadata approach, I want to double-check whether we're
>> all on the same page with regard to what the typed approach might entail,
>> particularly when configurability options are added. The examples
>> below are an attempt to assess this at a greater level of detail.
>>
>> First, consider an example of the typed approach without configurability
>> options. For JMS Connection Factory resources, an annotation might
>> potentially be defined as follows:
>>
>>
>> @Retention(RUNTIME)
>> @Target({TYPE, METHOD, FIELD})
>> public @interface JMSConnectionFactory {
>> String description() default "";
>> String name();
>> String resourceType() default "javax.jms.ConnectionFactory";
>> String resourceAdapterName() default "";
>> String user() default "";
>> String password() default "";
>> String clientId() default "";
>> boolean transactional() default true;
>> int initialPoolSize() default -1;
>> int maxPoolSize() default -1;
>> int minPoolSize() default -1;
>> int maxIdleTime() default -1;
>> int connectionTimeout() default -1;
>> String[] properties() default {};
>> }
>>
>>
>> Now, for each of these elements, if we add a configurability
>> specification, we need to replace the primitive-valued element with an
>> annotation-valued one. To preserve typing, some (or all??) of these
>> would entail the use of separate annotation types, as below. I've
>> defined default values for these to try to reduce verbosity. If we take
>> such an approach, we'd need to make sure we set defaults appropriately
>> (i.e., the defaults below should be regarded as a strawman for now). Ditto
>> for the use of "value" elements.
>>
>>
>> For example:
>>
>> @Retention(RUNTIME)
>> @Target{}
>> public @interface Name {
>> String name() default "";
>> Configurability configurability() default Configurability.MAY_MODIFY;
>> }
>>
>> @Retention(RUNTIME)
>> @Target{}
>> public @interface ResourceType {
>> String type() default "javax.jms.ConnectionFactory";
>> Configurability configurability() default Configurability.MAY_MODIFY;
>> }
>>
>> @Retention(RUNTIME)
>> @Target{}
>> public @interface ResourceAdapterName {
>> String name() default "";
>> Configurability configurability() default Configurability.MAY_MODIFY;
>> }
>>
>> @Retention(RUNTIME)
>> @Target{}
>> public @interface User {
>> String value() default "";
>> Configurability configurability() default Configurability.MAY_MODIFY;
>> }
>>
>> @Retention(RUNTIME)
>> @Target{}
>> public @interface Password {
>> String value() default "";
>> Configurability configurability() default Configurability.MAY_MODIFY;
>> }
>>
>> @Retention(RUNTIME)
>> @Target{}
>> public @interface ClientId {
>> String value() default "";
>> Configurability configurability() default Configurability.MUST_MODIFY;
>> }
>>
>> @Retention(RUNTIME)
>> @Target{}
>> public @interface Transactional {
>> boolean value() default true;
>> Configurability configurability() default Configurability.MAY_MODIFY;
>> }
>>
>> @Retention(RUNTIME)
>> @Target{}
>> public @interface PoolSize {
>> int value() default -1;
>> Configurability configurability() default Configurability.MAY_MODIFY;
>> }
>>
>>
>> @Retention(RUNTIME)
>> @Target{}
>> public @interface MaxIdleTime {
>> int value() default -1;
>> Configurability configurability() default Configurability.MAY_MODIFY;
>> }
>>
>> @Retention(RUNTIME)
>> @Target{}
>> public @interface Timeout {
>> int value() default -1;
>> Configurability configurability() default Configurability.MAY_MODIFY;
>> }
>>
>> @Retention(RUNTIME)
>> @Target{}
>> public @interface Property {
>> String name();
>> String value();
>> Configurability configurability() default Configurability.MAY_MODIFY;
>> }
>>
>>
>> Our expanded annotation then looks something like this:
>>
>> @Retention(RUNTIME)
>> @Target({TYPE, METHOD, FIELD})
>> public @interface JMSConnectionFactory {
>> String description() default "";
>> Name name() default @Name;
>> ResourceType resourceType() default @ResourceType;
>> ResourceAdapterName resourceAdapterName() default @ResourceAdapterName;
>> User user() default @User;
>> Password password() default @Password;
>> ClientId clientId() default @ClientId;
>> Transactional transactional() default @Transactional;
>> PoolSize initialPoolSize() default @PoolSize;
>> PoolSize maxPoolSize() default @PoolSize;
>> PoolSize minPoolSize() default @PoolSize;
>> MaxIdleTime maxIdleTime() default @IdleTime;
>> Timeout connectionTimeout() default @Timeout;
>> Properties[] properties() default {};
>> }
>>
>>
>> The filled out version appearing in application code might look like this
>> (assuming some use of defaults):
>>
>> @JMSConnectionFactory (
>> description="my JMF CF",
>> name=_at_Name(name="myJMSCF", configurability=MUST_NOT_MODIFY),
>> resourceType=_at_ResourceType(type="javax.jms.QueueConnectionFactory"),
>> resourceAdapterName=_at_ResourceAdapterName(name="myRA"),
>> clientId=_at_ClientId("foo"),
>> initialPoolSize = @PoolSize(2),
>> minPoolSize = @PoolSize(2),
>> properties = {_at_Property(name="vendorProp1",
>> value="someValue",
>> configurability=MUST_NOT_MODIFY},
>> @Property(name="vendorProp2",
>> value="someValue"),
>> @Property(name="vendorProp3",
>> value="someValue")}
>> )
>>
>>
>>
>> Is this what you have in mind in terms of the resource-specific approach?
>>
>> If so, are you sure this is what you want?
>>
>> Or something else?
>>
>>
>> thanks again,
>>
>> -Linda
>>
>>
>>
>>
>> On 8/25/2011 6:13 PM, 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: 10.0.1392 / Virus Database: 1520/3886 - Release Date: 09/09/11
>>
>>
>