javaee-spec
  1. javaee-spec
  2. JAVAEE_SPEC-7

Clarify and improve @DataSourceDefinition

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Labels:
      None

      Description

      Java EE 6 introduced the @DataSourceDefinition and corresponding data-source deployment descriptor element to allow an application to define a DataSource. (see JSR 316 EE.5.17 and JSR 250 2.13)

      This opens the door for creating both self-contained applications (i.e. for which an administrator does not need to setup anything before the application can be deployed and started) and applications that have a portable DataSource definition.

      However, in practice it's still not entirely possible to fully use this and use this portably due to a few omissions in the spec.

      One problem is that the spec does not say anything about the location of the required JDBC driver. JSR 250 does say in section 2.13:

      The driver class is not required to be available at deployment but must be available at runtime prior to any attempt to access the DataSource.

      In order to create a self-contained application that defines a DataSource in the java:comp, java:module or java:app JNDI namespaces, the user should be able to place the driver on the classpath corresponding to the components which can access those namespaces. E.g. WEB-INF/lib for the web module. Currently this is possible with e.g. JBoss AS 7.1, but not with GlassFish 3.1.

      Another problem is that the spec is not really clear about the transactional behavior. An example from which behavior can be deduced is given in JSR 250 section 2.13:

      Vendors are not required to support properties that do not normally apply to a specific data source type. For example, specifying the transactional property to be true but supplying a value for className that implements a data source class other than XADataSource may not be supported.

      Since this is non-trivial functionality, a somewhat more in depth specification of the desired behavior might not be out of place.

      The annotation and xml variant define attributes for pooling, but pooling is seemingly not mandated. JSR 250 calls those attributes "vendor specific". As a result, at least one vendor (JBoss) treats the annotation as a facility for testing and development only in its certified product:

      Since Java EE6, the new annotation "@DataSourceDefinition" has existed to allow users to configure a data source directly from within their application. (Note that this annotation bypasses the management layer and as such it is recommended only for development and testing purposes.)

      (source: https://community.jboss.org/wiki/DataSourceConfigurationInAS7)

      To sum up, I would like to request the following improvements:

      • Specify all valid locations of the JDBC driver
      • Mandate possibility to use application embedded JDBC driver for application scoped datasources
      • Clarify transactional behavior
      • Mandate connection pooling

      I hope that with these improvements @DataSourceDefinition/data-source can become a facility that is more likely to be used for actual production work.

        Activity

        arjan tijms created issue -
        ldemichiel made changes -
        Field Original Value New Value
        Assignee lancea [ lancea ]
        Hide
        arjan tijms added a comment -

        Common Annotations made some tiny clarifications for @DataSourceDefinition in the 1.2mr: http://java.net/projects/javaee-spec/pages/CommonAnnotations1_2MR

        Show
        arjan tijms added a comment - Common Annotations made some tiny clarifications for @DataSourceDefinition in the 1.2mr: http://java.net/projects/javaee-spec/pages/CommonAnnotations1_2MR
        Hide
        lancea added a comment -

        Yes, we made some minor clarifications to the annotation

        The Java EE platform specification does not mandate that JDBC Connection Pooling must be supported (EE6.2.4.2) nor does it mandate where JDBC drivers must be installed. This annotation makes no additional requirements, it is there more for an ease of use for configuration and the driver is not required to be there until the application is executed, not at deployment time.

        The available properties depend on the type of DataSource being used.

        For example if you are specifying a DataSource class, the Connection Pool properties are not necessarily relevant based on the implementation so they can be ignored

        Show
        lancea added a comment - Yes, we made some minor clarifications to the annotation The Java EE platform specification does not mandate that JDBC Connection Pooling must be supported (EE6.2.4.2) nor does it mandate where JDBC drivers must be installed. This annotation makes no additional requirements, it is there more for an ease of use for configuration and the driver is not required to be there until the application is executed, not at deployment time. The available properties depend on the type of DataSource being used. For example if you are specifying a DataSource class, the Connection Pool properties are not necessarily relevant based on the implementation so they can be ignored
        Hide
        arjan tijms added a comment -

        The Java EE platform specification does not mandate that JDBC Connection Pooling must be supported (EE6.2.4.2) nor does it mandate where JDBC drivers must be installed.

        I hope that that can be changed eventually, hence this issue

        As for the JDBC driver, in case of an application scoped datasource it's important that the driver can at least be loaded from the application archive. This is specifically important for embedded databases, where the driver isn't just a driver but is actually the entire database itself (e.g. h2, derby, etc). It makes little sense that a privately scoped database that's used internally by a single application has to be installed at some location deep inside the AS installation. The vendor can still be free to provide proprietary additional locations of course.

        In practice this requirement should be relatively easy to implement, as nearly all vendors that support @DataSourceDefinition already support loading the driver from the application archive. As far as I know, GlassFish is the only exception.

        As for the JDBC connection pooling, the idea is that if the vendor already supports connection pooling via their proprietary datasource syntax, then it should also be supported for @DataSourceDefinition. The goal is that vendors do not degrade @DataSourceDefinition (perhaps accidentally), so that even though a standard syntax exists users are still more or less forced to use the proprietary syntax.

        I understand this connection pooling might be hard to put in the spec, but merely stating that the spirit of the spec is that @DataSourceDefinition can be used for production (and not just for test/demo apps) might already be an improvement.

        Show
        arjan tijms added a comment - The Java EE platform specification does not mandate that JDBC Connection Pooling must be supported (EE6.2.4.2) nor does it mandate where JDBC drivers must be installed. I hope that that can be changed eventually, hence this issue As for the JDBC driver, in case of an application scoped datasource it's important that the driver can at least be loaded from the application archive. This is specifically important for embedded databases, where the driver isn't just a driver but is actually the entire database itself (e.g. h2, derby, etc). It makes little sense that a privately scoped database that's used internally by a single application has to be installed at some location deep inside the AS installation. The vendor can still be free to provide proprietary additional locations of course. In practice this requirement should be relatively easy to implement, as nearly all vendors that support @DataSourceDefinition already support loading the driver from the application archive. As far as I know, GlassFish is the only exception. As for the JDBC connection pooling, the idea is that if the vendor already supports connection pooling via their proprietary datasource syntax, then it should also be supported for @DataSourceDefinition . The goal is that vendors do not degrade @DataSourceDefinition (perhaps accidentally), so that even though a standard syntax exists users are still more or less forced to use the proprietary syntax. I understand this connection pooling might be hard to put in the spec, but merely stating that the spirit of the spec is that @DataSourceDefinition can be used for production (and not just for test/demo apps) might already be an improvement.
        Hide
        rmannibucau added a comment -

        + the jndi name shouldn't be ambiguous anymore. basically container resources are in a container specific jndi tree but allowing to specify "jndi name" doesn't explicitly mean you can bind in java:app/ or java:global/ (defined for EJBs not for other parts). Basically in JavaEE a datasource name should be relative (jdbc/foo for instance) but some server use absolute jndi name.

        This slow down portability and should be addressed too.

        Show
        rmannibucau added a comment - + the jndi name shouldn't be ambiguous anymore. basically container resources are in a container specific jndi tree but allowing to specify "jndi name" doesn't explicitly mean you can bind in java:app/ or java:global/ (defined for EJBs not for other parts). Basically in JavaEE a datasource name should be relative (jdbc/foo for instance) but some server use absolute jndi name. This slow down portability and should be addressed too.
        Hide
        arjan tijms added a comment -

        the jndi name shouldn't be ambiguous anymore. basically container resources are in a container specific jndi tree but allowing to specify "jndi name" doesn't explicitly mean you can bind in java:app/ or java:global/ (defined for EJBs not for other parts).

        I'm not a big JNDI expert, but if that's indeed the case it should definitely be addressed! The spec does explicitly defines that java:app and java:global among others should be supported.

        EE.5.17:

        The DataSource resource may be defined in any of the JNDI namespaces described in Section EE.5.2.2, “Application Component Environment Namespaces”. For example, aDataSourceresource may be defined:

        • in the java:comp namespace, for use by a single component;
        • in the java:module namespace, for use by all components in a module;
        • in the java:app namespace, for use by all components in an application;
        • in the java:global namespace, for use by all applications.

        Then EE.5.2.2 does not mention that those namespaces are only defined for EJB beans, or EJB modules:

        The application component’s naming environment is composed of four logical namespaces, representing naming environments with different scopes. The four namespaces are:

        • java:comp - Names in this namespace are per-component (for example, per enterprise bean). Except for components in a web module, each component gets its own java:comp namespace, not shared with any other component. Components in a web module do not have their own private component namespace. See note below.
        • java:module - Names in this namespace are shared by all components in a module (for example, all enterprise beans in a single EJB module, or all com- ponents in a web module).
        • java:app - Names in this namespace are shared by all components in all modules in a single application, where “single application” means a single deployment unit, such as a single ear file, a single module deployed standalone, etc. For example, a war file and an EJB jar file in the same ear file would both have access to resources in the java:app namespace.
        • java:global - Names in this namespace are shared by all applications de- ployed in an application server instance. Note that an application server in- stance may represent a single server, a cluster of servers, an administrative domain containing many servers, or even more. The scope of an application server instance is product-dependent, but it must be possible to deploy multiple applications to a single application server instance.

        EE.5.7.1.1 gives another example of using java:app for something that is not an EJB:

        It is possible to specify as part of the @Resource annotation the JNDI name of
        an entry to which the resource being defined will be bound.

        // The customer database, looked up in the application environment. 
        @Resource(lookup=”java:app/env/customerDB”) javax.sql.DataSource customerAppDB;
        

        EE.5.18 explicitly defines that java:app can be used for a "Managed Bean" and contrasts this to EJB:

        An instance of a named Managed Bean can be obtained by looking up its name in JNDI using the same naming scheme used for EJB components:

        java:app/<module-name>/<bean-name>
        
        Show
        arjan tijms added a comment - the jndi name shouldn't be ambiguous anymore. basically container resources are in a container specific jndi tree but allowing to specify "jndi name" doesn't explicitly mean you can bind in java:app/ or java:global/ (defined for EJBs not for other parts). I'm not a big JNDI expert, but if that's indeed the case it should definitely be addressed! The spec does explicitly defines that java:app and java:global among others should be supported. EE.5.17: The DataSource resource may be defined in any of the JNDI namespaces described in Section EE.5.2.2, “Application Component Environment Namespaces”. For example, aDataSourceresource may be defined: in the java:comp namespace, for use by a single component; in the java:module namespace, for use by all components in a module; in the java:app namespace, for use by all components in an application; in the java:global namespace, for use by all applications. Then EE.5.2.2 does not mention that those namespaces are only defined for EJB beans, or EJB modules: The application component’s naming environment is composed of four logical namespaces, representing naming environments with different scopes. The four namespaces are: java:comp - Names in this namespace are per-component (for example, per enterprise bean). Except for components in a web module, each component gets its own java:comp namespace, not shared with any other component. Components in a web module do not have their own private component namespace. See note below. java:module - Names in this namespace are shared by all components in a module (for example, all enterprise beans in a single EJB module, or all com- ponents in a web module). java:app - Names in this namespace are shared by all components in all modules in a single application, where “single application” means a single deployment unit, such as a single ear file, a single module deployed standalone, etc. For example, a war file and an EJB jar file in the same ear file would both have access to resources in the java:app namespace. java:global - Names in this namespace are shared by all applications de- ployed in an application server instance. Note that an application server in- stance may represent a single server, a cluster of servers, an administrative domain containing many servers, or even more. The scope of an application server instance is product-dependent, but it must be possible to deploy multiple applications to a single application server instance. EE.5.7.1.1 gives another example of using java:app for something that is not an EJB: It is possible to specify as part of the @Resource annotation the JNDI name of an entry to which the resource being defined will be bound. // The customer database, looked up in the application environment. @Resource(lookup=”java:app/env/customerDB”) javax.sql.DataSource customerAppDB; EE.5.18 explicitly defines that java:app can be used for a "Managed Bean" and contrasts this to EJB: An instance of a named Managed Bean can be obtained by looking up its name in JNDI using the same naming scheme used for EJB components: java:app/<module-name>/<bean-name>
        Hide
        rmannibucau added a comment -

        the main point is it is sticked to EE world so not usable from not managed beans. In other words it doesn't define a user namespace but a EE user namespace. I'm fine with this definition but it should be at least explicit.

        A sample ambiguous for me:

        a cdi bean starts a thread, the thread does a new MyPojo() and MyPojo does a lookup in java:app: should it work? reading the spec i don't understand it should.

        Show
        rmannibucau added a comment - the main point is it is sticked to EE world so not usable from not managed beans. In other words it doesn't define a user namespace but a EE user namespace. I'm fine with this definition but it should be at least explicit. A sample ambiguous for me: a cdi bean starts a thread, the thread does a new MyPojo() and MyPojo does a lookup in java:app: should it work? reading the spec i don't understand it should.
        Hide
        Bill Shannon added a comment -

        All the java: JNDI names are defined by the spec and are portable.
        If you're using a JNDI name that doesn't start with java:, it's
        product-specific.

        Yes, it's true that the Java EE spec defines a Java EE namespace.
        Are you wondering whether any of these JNDI names work in plain Java SE?
        They're not required to.

        Show
        Bill Shannon added a comment - All the java: JNDI names are defined by the spec and are portable. If you're using a JNDI name that doesn't start with java:, it's product-specific. Yes, it's true that the Java EE spec defines a Java EE namespace. Are you wondering whether any of these JNDI names work in plain Java SE ? They're not required to.
        Hide
        Bill Shannon added a comment -

        Note also that the defined way to package a JDBC driver with an application
        is to package it as a Resource Adapter and include the rar file in the ear file.

        Still, it seems like putting the JDBC driver in WEB-INF/lib should also work.
        If it doesn't, please file a bug against GlassFish.

        We need to see if there's anything in the spec that needs to be clarified in this area.

        Show
        Bill Shannon added a comment - Note also that the defined way to package a JDBC driver with an application is to package it as a Resource Adapter and include the rar file in the ear file. Still, it seems like putting the JDBC driver in WEB-INF/lib should also work. If it doesn't, please file a bug against GlassFish. We need to see if there's anything in the spec that needs to be clarified in this area.
        Hide
        arjan tijms added a comment -

        Note also that the defined way to package a JDBC driver with an application is to package it as a Resource Adapter and include the rar file in the ear file.

        This might be an option for ears indeed (I've never tried it though), but as ease of use goes, just dropping it in EAR/lib is probably easier. For a web profile implementation and/or a war, a .rar is unfortunately not an option.

        If it doesn't, please file a bug against GlassFish.

        I filed this one a short while ago. It's at: GLASSFISH-19451

        Show
        arjan tijms added a comment - Note also that the defined way to package a JDBC driver with an application is to package it as a Resource Adapter and include the rar file in the ear file. This might be an option for ears indeed (I've never tried it though), but as ease of use goes, just dropping it in EAR/lib is probably easier. For a web profile implementation and/or a war, a .rar is unfortunately not an option. If it doesn't, please file a bug against GlassFish. I filed this one a short while ago. It's at: GLASSFISH-19451
        Hide
        rmannibucau added a comment -

        So basically using spring i have no gurantee i can acces these jndi names (not manged beans) + what does mean managed beans? Ejb, cdi, javax.annotation.ManagedBean? That's totally unclear in specs in general.

        Show
        rmannibucau added a comment - So basically using spring i have no gurantee i can acces these jndi names (not manged beans) + what does mean managed beans? Ejb, cdi, javax.annotation.ManagedBean? That's totally unclear in specs in general.
        Hide
        Bill Shannon added a comment -

        The Java EE spec does not and will not describe what you can do in Spring.
        For that, you'll need to read the Spring spec.

        If there's something you still feel isn't clear in the Java EE spec, please
        file a new issue. The original issue here has been addressed and I'm closing
        this issue.

        Show
        Bill Shannon added a comment - The Java EE spec does not and will not describe what you can do in Spring. For that, you'll need to read the Spring spec. If there's something you still feel isn't clear in the Java EE spec, please file a new issue. The original issue here has been addressed and I'm closing this issue.
        Bill Shannon made changes -
        Status Open [ 1 ] Closed [ 6 ]
        Resolution Fixed [ 1 ]

          People

          • Assignee:
            lancea
            Reporter:
            arjan tijms
          • Votes:
            3 Vote for this issue
            Watchers:
            3 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: