Derby
  1. Derby
  2. DERBY-6059

Document Derby usage running on Java 8 JEP 161 Compact Profiles

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 10.10.1.1
    • Component/s: Documentation
    • Labels:
      None

      Description

      Document that Derby can run even under constrained Java runtime as planned for Java 8 Compact Profiles 2 and 3 (not 1, the smallest runtime, since it has no JDBC). Cf work in DERBY-5955 which made Derby run gracefully even when some normal Java runtime packages are missing, notably JNDI and JMX.

      That work introduced six new data sources which have reduced functionality compared with the corresponding ones for full Java SE, in that there is no JNDI support. The six new data sources are for the client driver:

      Client/server data sources for use with Java 8 Compact Profile 2 and above:

      BasicClientDataSource40 - Data source
      BasicClientConnectionPoolDataSource40 - Connection pooling data source
      BasicClientXADataSource40 - XA data source

      Embedded data sources for use with Java 8 Compact Profile 2 and above:

      BasicEmbeddedDataSource40 - Data source
      BasicEmbeddedConnectionPoolSource40 - Connection pooling data source
      BasicEmbeddedXASource40 - XA data source

      1. rrefattribtracelevel.html
        10 kB
        Kim Haase
      2. DERBY-6059-2.stat
        0.0 kB
        Kim Haase
      3. DERBY-6059-2.diff
        0.7 kB
        Kim Haase
      4. DERBY-6059.zip
        36 kB
        Kim Haase
      5. DERBY-6059.stat
        0.7 kB
        Kim Haase
      6. DERBY-6059.diff
        39 kB
        Kim Haase
      7. javadoc-snapshot.pdf
        139 kB
        Dag H. Wanvik

        Issue Links

          Activity

          Hide
          Kim Haase added a comment -

          Closing, since changes appeared in the 10.10.1.1 documentation.

          Show
          Kim Haase added a comment - Closing, since changes appeared in the 10.10.1.1 documentation.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-6059-2.diff to documentation trunk at revision 1445829.

          Show
          Kim Haase added a comment - Committed patch DERBY-6059 -2.diff to documentation trunk at revision 1445829.
          Hide
          Kim Haase added a comment -

          Attaching DERBY-6059-2.diff, DERBY-6059-2.stat, and rrefattribtracelevel.html, with the space correction.

          M src/ref/rrefattribtracelevel.dita

          I will commit this patch shortly.

          Show
          Kim Haase added a comment - Attaching DERBY-6059 -2.diff, DERBY-6059 -2.stat, and rrefattribtracelevel.html, with the space correction. M src/ref/rrefattribtracelevel.dita I will commit this patch shortly.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-6059.diff to documentation trunk at revision 1445699.

          Stay tuned for another patch.

          Show
          Kim Haase added a comment - Committed patch DERBY-6059 .diff to documentation trunk at revision 1445699. Stay tuned for another patch.
          Hide
          Kim Haase added a comment -

          Thanks for catching that, Dag, and for the careful review. I will commit this patch and then file another for the smaller fix. If you see anything else, let me know.

          Show
          Kim Haase added a comment - Thanks for catching that, Dag, and for the careful review. I will commit this patch and then file another for the smaller fix. If you see anything else, let me know.
          Hide
          Dag H. Wanvik added a comment -

          Thanks, Kim. Looks good!

          Nit:
          rrefattribtracelevel.html: lacking space before "class" in this sentence: "You must use the org.apache.derby.jdbc.BasicClientDataSource40class", at least in my browser (Firefox 18.0.2).

          Show
          Dag H. Wanvik added a comment - Thanks, Kim. Looks good! Nit: rrefattribtracelevel.html: lacking space before "class" in this sentence: "You must use the org.apache.derby.jdbc.BasicClientDataSource40class", at least in my browser (Firefox 18.0.2).
          Hide
          Kim Haase added a comment -

          Attaching DERBY-6059.diff, DERBY-6059.stat, and DERBY-6059.zip. This patch modifies 4 Admin Guide topics, one Dev Guide topic, and 7 Reference Manual topics (plus the map file); adds 3 new Reference Manual topics (two for JDBC 4.2/Compact Profies, and one JDBC 4.1 datasource topic to parallel the other two.

          M src/devguide/rdevresman79556.dita
          M src/adminguide/cadminappsclientsecurity.dita
          M src/adminguide/cadminappsxawthdriver.dita
          M src/adminguide/cadminappsclienttracing.dita
          M src/adminguide/cadminnsdatasources.dita
          M src/ref/rrefjdbc4_0dataSource.dita
          M src/ref/rrefjta18596.dita
          M src/ref/rrefapi1003363.dita
          M src/ref/rrefjdbc4_1summary.dita
          M src/ref/refderby.ditamap
          A src/ref/rrefjdbc4_2compactprofiles.dita
          A src/ref/rrefjdbc4_1datasource.dita
          M src/ref/rrefjta16677.dita
          A src/ref/rrefjdbc4_2summary.dita
          M src/ref/rrefjdbc4_0summary.dita
          M src/ref/rrefattribtracelevel.dita

          Show
          Kim Haase added a comment - Attaching DERBY-6059 .diff, DERBY-6059 .stat, and DERBY-6059 .zip. This patch modifies 4 Admin Guide topics, one Dev Guide topic, and 7 Reference Manual topics (plus the map file); adds 3 new Reference Manual topics (two for JDBC 4.2/Compact Profies, and one JDBC 4.1 datasource topic to parallel the other two. M src/devguide/rdevresman79556.dita M src/adminguide/cadminappsclientsecurity.dita M src/adminguide/cadminappsxawthdriver.dita M src/adminguide/cadminappsclienttracing.dita M src/adminguide/cadminnsdatasources.dita M src/ref/rrefjdbc4_0dataSource.dita M src/ref/rrefjta18596.dita M src/ref/rrefapi1003363.dita M src/ref/rrefjdbc4_1summary.dita M src/ref/refderby.ditamap A src/ref/rrefjdbc4_2compactprofiles.dita A src/ref/rrefjdbc4_1datasource.dita M src/ref/rrefjta16677.dita A src/ref/rrefjdbc4_2summary.dita M src/ref/rrefjdbc4_0summary.dita M src/ref/rrefattribtracelevel.dita
          Hide
          Kristian Waagan added a comment -

          > I can see that this is tricky to document and puzzling to users. Maybe we could help users by adding the following factory methods to, say, EmbeddedDriver and ClientDriver:

          While this may help in some cases, note that configuring systems using data sources often consists of specifying the data source class as a text string.
          As such I think it is important that we document this as good as we can.

          Show
          Kristian Waagan added a comment - > I can see that this is tricky to document and puzzling to users. Maybe we could help users by adding the following factory methods to, say, EmbeddedDriver and ClientDriver: While this may help in some cases, note that configuring systems using data sources often consists of specifying the data source class as a text string. As such I think it is important that we document this as good as we can.
          Hide
          Rick Hillegas added a comment -

          Java 8 will increase the number of JDBC methods which are only available from the 40 data sources. So the distinction is becoming more important for portable applications.

          I can see that this is tricky to document and puzzling to users. Maybe we could help users by adding the following factory methods to, say, EmbeddedDriver and ClientDriver:

          public static javax.sql.DataSource getDataSource()

          public static javax.sql.ConnectionPoolDataSource() getConnectionPoolDataSource()

          public static javax.sql.XADataSource getXADataSource()

          Thanks,
          -Rick

          Show
          Rick Hillegas added a comment - Java 8 will increase the number of JDBC methods which are only available from the 40 data sources. So the distinction is becoming more important for portable applications. I can see that this is tricky to document and puzzling to users. Maybe we could help users by adding the following factory methods to, say, EmbeddedDriver and ClientDriver: public static javax.sql.DataSource getDataSource() public static javax.sql.ConnectionPoolDataSource() getConnectionPoolDataSource() public static javax.sql.XADataSource getXADataSource() Thanks, -Rick
          Hide
          Dag H. Wanvik added a comment -

          I still think we should recommend that for Java >= 7, users should use the "40" suffixed versions, although it may not be necessary unless they rely on the getParentLogger method as Knut says. Just to keep it simple(r).. Others opinions on this?

          Show
          Dag H. Wanvik added a comment - I still think we should recommend that for Java >= 7, users should use the "40" suffixed versions, although it may not be necessary unless they rely on the getParentLogger method as Knut says. Just to keep it simple(r).. Others opinions on this?
          Hide
          Knut Anders Hatlen added a comment -

          Hi Kim,

          You're right, the 40 classes are not required for Java 7. They are only required if you call the getParentLogger() method, which was new in JDBC 4.1. Since our implementation of that method always throws SQLFeatureNotSupportedException, I don't think it's very likely that our users will have applications that depend on that method.

          So we have the plain (unsuffixed) data sources that can be used on Java SE 5 and newer, as long as you stick to the JDBC 4.0 subset of the API. And the "40" classes can be used on Java SE 6 and newer, as long as you stick to the JDBC 4.1 subset of the API (or possibly JDBC 4.2, as I don't think any new methods are planned in the data sources for 4.2).

          Show
          Knut Anders Hatlen added a comment - Hi Kim, You're right, the 40 classes are not required for Java 7. They are only required if you call the getParentLogger() method, which was new in JDBC 4.1. Since our implementation of that method always throws SQLFeatureNotSupportedException, I don't think it's very likely that our users will have applications that depend on that method. So we have the plain (unsuffixed) data sources that can be used on Java SE 5 and newer, as long as you stick to the JDBC 4.0 subset of the API. And the "40" classes can be used on Java SE 6 and newer, as long as you stick to the JDBC 4.1 subset of the API (or possibly JDBC 4.2, as I don't think any new methods are planned in the data sources for 4.2).
          Hide
          Kim Haase added a comment -

          Thanks, Dag and Knut, that clarifies matters a lot.

          I'm still a little bit confused by the statement that "For Java 7 (JDBC 4.1) it is required [to use the '40' data sources]." We have been saying (in http://db.apache.org/derby/docs/10.9/adminguide/cadminnsdatasources.html, for instance) that you can use the old data sources on all platforms:

          "The Network Server supports the Derby Network Client driver DataSource classes org.apache.derby.jdbc.ClientDataSource and org.apache.derby.jdbc.ClientConnectionPoolDataSource on all supported Java SE platforms." (It's a bit confusing that the XA ones are not mentioned, but they are in the next section.)

          If you are running on Java SE 7, it seems that you cannot use these but must use the "40" versions? Or is that the case (as we have been saying) only if you want to use the APIs specific to JDBC 4.1? If you have an app that uses only JDBC 3 methods, can you use the basic org.apache.derby.jdbc.ClientDataSource (etc.) DataSources on SE 6, 7, and 8 if you want?

          Just checking ... Thanks!

          Show
          Kim Haase added a comment - Thanks, Dag and Knut, that clarifies matters a lot. I'm still a little bit confused by the statement that "For Java 7 (JDBC 4.1) it is required [to use the '40' data sources] ." We have been saying (in http://db.apache.org/derby/docs/10.9/adminguide/cadminnsdatasources.html , for instance) that you can use the old data sources on all platforms: "The Network Server supports the Derby Network Client driver DataSource classes org.apache.derby.jdbc.ClientDataSource and org.apache.derby.jdbc.ClientConnectionPoolDataSource on all supported Java SE platforms." (It's a bit confusing that the XA ones are not mentioned, but they are in the next section.) If you are running on Java SE 7, it seems that you cannot use these but must use the "40" versions? Or is that the case (as we have been saying) only if you want to use the APIs specific to JDBC 4.1? If you have an app that uses only JDBC 3 methods, can you use the basic org.apache.derby.jdbc.ClientDataSource (etc.) DataSources on SE 6, 7, and 8 if you want? Just checking ... Thanks!
          Hide
          Knut Anders Hatlen added a comment -

          Dag is correct. DERBY-5880 made the suffix-less data sources more capable, and the javadoc comments were updated to reflect the new reality. The suffix-less data sources can (still) be used on JDBC 3.0 platforms, but now they also support the full JDBC 4.0 API. The data sources with the "40" suffix require at least JDBC 4.0 support in the JVM, otherwise the classes will fail to load. They support the full JDBC 4.1 API.

          I guess we should add a sentence to the javadoc of the 40-suffixed classes to say that they will also work on Java SE 6/JDBC 4.0. They will have to continue supporting that platform for backward compatibility reasons, and we could just as well say that explicitly in the javadoc. That might make the naming less confusing too.

          Show
          Knut Anders Hatlen added a comment - Dag is correct. DERBY-5880 made the suffix-less data sources more capable, and the javadoc comments were updated to reflect the new reality. The suffix-less data sources can (still) be used on JDBC 3.0 platforms, but now they also support the full JDBC 4.0 API. The data sources with the "40" suffix require at least JDBC 4.0 support in the JVM, otherwise the classes will fail to load. They support the full JDBC 4.1 API. I guess we should add a sentence to the javadoc of the 40-suffixed classes to say that they will also work on Java SE 6/JDBC 4.0. They will have to continue supporting that platform for backward compatibility reasons, and we could just as well say that explicitly in the javadoc. That might make the naming less confusing too.
          Hide
          Dag H. Wanvik added a comment -

          Kim, your reading is very observant. I believe at one point (DERBY-5880), we were able to move that 4.0 specific additions into the plain data sources, making the suffix "40" a tad confusing indeed. Using the "40" data sources for Java 1.6 (jdbc 4.0) is still fine, it is just no longer required (and they are slightly more capable than required by 4.0). For Java 7 (JDBC 4.1) it is required. Ideally, the classes would now be suffixed with "41"...

          Show
          Dag H. Wanvik added a comment - Kim, your reading is very observant. I believe at one point ( DERBY-5880 ), we were able to move that 4.0 specific additions into the plain data sources, making the suffix "40" a tad confusing indeed. Using the "40" data sources for Java 1.6 (jdbc 4.0) is still fine, it is just no longer required (and they are slightly more capable than required by 4.0). For Java 7 (JDBC 4.1) it is required. Ideally, the classes would now be suffixed with "41"...
          Hide
          Kim Haase added a comment -

          We seem to be inconsistent about what our DataSource implementations support.

          In the updated Javadoc – for example, https://builds.apache.org/job/Derby-trunk/lastSuccessfulBuild/artifact/trunk/javadoc/engine/org/apache/derby/jdbc/ClientDataSource40.html – it says that plain ClientDataSource is suitable for Java SE 6 (JDBC 4.0) and below, and that ClientDataSource40 is suitable for Java SE 7 (JDBC 4.1) and above. However, in the Reference Manual (http://db.apache.org/derby/docs/10.9/ref/rrefjdbc4_0dataSource.html and http://db.apache.org/derby/docs/10.9/ref/rrefapi1003363.html, for example) we have been saying that the plain version (ClientDataSource etc.) is for Java SE 5 (JDBC 3) and that ClientDataSource40 is suitable for Java SE 6 (JDBC 4.0) and higher. This is also what we said in the Javadoc at 10.9: http://db.apache.org/derby/docs/10.9/publishedapi/jdbc4/org/apache/derby/jdbc/ClientDataSource40.html

          On the face of it it would seem as if a class with the "40" suffix should be meant for JDBC 4.0 and above, which is what we have been saying, and that the latest Javadoc needs fixing. Is this so? Thanks!

          Show
          Kim Haase added a comment - We seem to be inconsistent about what our DataSource implementations support. In the updated Javadoc – for example, https://builds.apache.org/job/Derby-trunk/lastSuccessfulBuild/artifact/trunk/javadoc/engine/org/apache/derby/jdbc/ClientDataSource40.html – it says that plain ClientDataSource is suitable for Java SE 6 (JDBC 4.0) and below, and that ClientDataSource40 is suitable for Java SE 7 (JDBC 4.1) and above. However, in the Reference Manual ( http://db.apache.org/derby/docs/10.9/ref/rrefjdbc4_0dataSource.html and http://db.apache.org/derby/docs/10.9/ref/rrefapi1003363.html , for example) we have been saying that the plain version (ClientDataSource etc.) is for Java SE 5 (JDBC 3) and that ClientDataSource40 is suitable for Java SE 6 (JDBC 4.0) and higher. This is also what we said in the Javadoc at 10.9: http://db.apache.org/derby/docs/10.9/publishedapi/jdbc4/org/apache/derby/jdbc/ClientDataSource40.html On the face of it it would seem as if a class with the "40" suffix should be meant for JDBC 4.0 and above, which is what we have been saying, and that the latest Javadoc needs fixing. Is this so? Thanks!
          Hide
          Dag H. Wanvik added a comment -

          Btw, the tracing level tables are duplicated in the reference manual and the admin manual as tables "Table 132. Available tracing levels and values" and "Table 8. Available tracing levels and values" respectively...

          Show
          Dag H. Wanvik added a comment - Btw, the tracing level tables are duplicated in the reference manual and the admin manual as tables "Table 132. Available tracing levels and values" and "Table 8. Available tracing levels and values" respectively...
          Hide
          Dag H. Wanvik added a comment -

          In the admin guide

          • we have section "Accessing the Network Server by using the network client driver", which describes the client data sources' properties. Again, some constants used there should now be accessed via BasicClientDataSource40 when running on Compact Profile 2, cf Table 7 "Security mechanisms supported by the Derby Network Client", e.g as ClientDataSource.USER_ONLY_SECURITY -> BasicClientDataSource40.USER_ONLY_SECURITY. Table 8 has the same issue. Rather than complicating these explanations by always mentioning the CP alternative, probably it would be better with just saying something about CP 2 in a separate section, or ? I'm sure you'll find a nice way
          • Section "Accessing the Network Server by using a DataSource object" explains what to do for different platforms, add Compact Profile 2 here as well.
          • The subsection "user authentication differences" mention those constants again; not sure whether it's worth bringing up the CP2 alternative here...
          Show
          Dag H. Wanvik added a comment - In the admin guide we have section "Accessing the Network Server by using the network client driver", which describes the client data sources' properties. Again, some constants used there should now be accessed via BasicClientDataSource40 when running on Compact Profile 2, cf Table 7 "Security mechanisms supported by the Derby Network Client", e.g as ClientDataSource.USER_ONLY_SECURITY -> BasicClientDataSource40.USER_ONLY_SECURITY. Table 8 has the same issue. Rather than complicating these explanations by always mentioning the CP alternative, probably it would be better with just saying something about CP 2 in a separate section, or ? I'm sure you'll find a nice way Section "Accessing the Network Server by using a DataSource object" explains what to do for different platforms, add Compact Profile 2 here as well. The subsection "user authentication differences" mention those constants again; not sure whether it's worth bringing up the CP2 alternative here...
          Hide
          Dag H. Wanvik added a comment - - edited

          Going through the docs looking for what you are referring to and found these items:

          refman

          • I see we mention the new *40 data sources in the section on JDBC 4.0
            and 4.1 features in the manual, maybe we should put something there
            for the new ones, too?
          • Just before it there is a section on "JDBC Package for Connected
            Device Configuration/Foundation Profile (JSR 169)"; we should
            probably put in a section something about Compact Profiles there,
            too.
          • There is a three column table "Table 132. Available tracing levels
            and values" which shows tracing levels for
            ClientDataSource.<TRACECONSTANTS> For CP2 level applications these constants should be
            referenced via BasicClientDataSource40.<TRACECONSTANTS> instead,
            since the class ClientDataSource is not loadable in a CP2
            environment.
          • In the section "J2EE compliance" we mention that our
            implementation(s) of the javax.sql.DataSource interface supports
            JNDI. We should mention that the new data sources are an exception
            to that.
          • In the section "Data Source Implementation Classes", we should
            include the new ones, too

          dev guide:

          • Section "Classes that pertain to resource managers" describe two
            variants, we now have three for each level, so needs
            update. Probably best the keep the existing section contents more or
            less intact, and just add description of the new at the end of it,
            or in a subsection?

          Not sure if any of these cover what you are referring to, though

          In the jdbc package Javadoc there is now an updated overview, cf. my attachment "javadoc-snapshot".

          Show
          Dag H. Wanvik added a comment - - edited Going through the docs looking for what you are referring to and found these items: refman I see we mention the new *40 data sources in the section on JDBC 4.0 and 4.1 features in the manual, maybe we should put something there for the new ones, too? Just before it there is a section on "JDBC Package for Connected Device Configuration/Foundation Profile (JSR 169)"; we should probably put in a section something about Compact Profiles there, too. There is a three column table "Table 132. Available tracing levels and values" which shows tracing levels for ClientDataSource.<TRACECONSTANTS> For CP2 level applications these constants should be referenced via BasicClientDataSource40.<TRACECONSTANTS> instead, since the class ClientDataSource is not loadable in a CP2 environment. In the section "J2EE compliance" we mention that our implementation(s) of the javax.sql.DataSource interface supports JNDI. We should mention that the new data sources are an exception to that. In the section "Data Source Implementation Classes", we should include the new ones, too dev guide: Section "Classes that pertain to resource managers" describe two variants, we now have three for each level, so needs update. Probably best the keep the existing section contents more or less intact, and just add description of the new at the end of it, or in a subsection? Not sure if any of these cover what you are referring to, though In the jdbc package Javadoc there is now an updated overview, cf. my attachment "javadoc-snapshot".
          Hide
          Kim Haase added a comment -

          I seem to remember seeing a 3-column list of the API methods in each of the 3 profiles, somewhere. I was wondering if it would be useful to point to it or reproduce it. Or is it in the Javadoc?

          Show
          Kim Haase added a comment - I seem to remember seeing a 3-column list of the API methods in each of the 3 profiles, somewhere. I was wondering if it would be useful to point to it or reproduce it. Or is it in the Javadoc?
          Hide
          Dag H. Wanvik added a comment -

          If you generate the Javadoc on trunk, you'll see in the jdbc package javadoc some more info, too.

          Show
          Dag H. Wanvik added a comment - If you generate the Javadoc on trunk, you'll see in the jdbc package javadoc some more info, too.
          Hide
          Dag H. Wanvik added a comment -

          Thanks for taking this on, Kim! Hmm... not sure I understand your question..These new classes represent the API change; do you mean the method details of them? How much do we reproduce in the docs from the Javadocs for the existing data sources?

          Seen from the user's point of view she needs to configure the appserver and/or change the application code to use "Basic" version of the data source(s) when running under Compact Profile 2. Also, the code should not attempt to use JNDI with them (examples shown in the Javadoc for the fully capable data sources).

          Show
          Dag H. Wanvik added a comment - Thanks for taking this on, Kim! Hmm... not sure I understand your question..These new classes represent the API change; do you mean the method details of them? How much do we reproduce in the docs from the Javadocs for the existing data sources? Seen from the user's point of view she needs to configure the appserver and/or change the application code to use "Basic" version of the data source(s) when running under Compact Profile 2. Also, the code should not attempt to use JNDI with them (examples shown in the Javadoc for the fully capable data sources).
          Hide
          Kim Haase added a comment -

          Thanks for creating this, Dag. Do you think we should list the supported APIs in addition to the data sources, or just point to them? Maybe you could post a link – I think there is one somewhere under DERBY-5955, but there's a lot of material there.

          Show
          Kim Haase added a comment - Thanks for creating this, Dag. Do you think we should list the supported APIs in addition to the data sources, or just point to them? Maybe you could post a link – I think there is one somewhere under DERBY-5955 , but there's a lot of material there.

            People

            • Assignee:
              Kim Haase
              Reporter:
              Dag H. Wanvik
            • Votes:
              0 Vote for this issue
              Watchers:
              6 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development