Derby
  1. Derby
  2. DERBY-5043

Document the new url attribute deregister to keep the AutoloadedDriver registers in DriverManager

    Details

    • Urgency:
      Blocker

      Description

      With DERBY-2905, we have a new connection url attribute - deregister. After a shutdown of the embedded driver, the AutoloadedDriver is unregistered from the DriverManager. Users who wish to keep the AutoloadedDriver can set the deregister attribute on the connection url to false. It is only valid with shutdown=true. And, the default behavior with shutdown=true is deregister=true.
      For example:
      'shutdown=true;deregister=true" (It is okay not to specify deregister=true)
      'shutdown=true;deregister=false"

      1. Repro2905.java
        6 kB
        Lily Wei
      2. DERBY-5043.diff
        6 kB
        Kim Haase
      3. DERBY-5043.stat
        0.1 kB
        Kim Haase
      4. DERBY-5043.zip
        4 kB
        Kim Haase
      5. DERBY-5043-2.diff
        6 kB
        Kim Haase
      6. DERBY-5043-2.zip
        4 kB
        Kim Haase

        Activity

        Hide
        Kim Haase added a comment -

        Fixes appeared in 10.8.1 documentation, so closing.

        Show
        Kim Haase added a comment - Fixes appeared in 10.8.1 documentation, so closing.
        Hide
        Kim Haase added a comment -

        Thanks for the quick review, Rick!

        Committed patch DERBY-5043-2.diff to documentation trunk at revision 1076431.

        I'll be happy to reopen this for additional fixes if needed – not everyone may have had a chance to review the patch.

        Show
        Kim Haase added a comment - Thanks for the quick review, Rick! Committed patch DERBY-5043 -2.diff to documentation trunk at revision 1076431. I'll be happy to reopen this for additional fixes if needed – not everyone may have had a chance to review the patch.
        Hide
        Rick Hillegas added a comment -

        Thanks for the quick adjustment, Kim. +1 to the new patch.

        Show
        Rick Hillegas added a comment - Thanks for the quick adjustment, Kim. +1 to the new patch.
        Hide
        Kim Haase added a comment -

        Thanks again, Rick. As you had advised originally, I'm just leaving autoloading out of the picture – I dropped that phrase. I also added a link to the topic on DriverManager.getConnection, for usability.

        Attaching DERBY-5043-2.diff and DERBY-5043-2.zip, with these changes.

        Show
        Kim Haase added a comment - Thanks again, Rick. As you had advised originally, I'm just leaving autoloading out of the picture – I dropped that phrase. I also added a link to the topic on DriverManager.getConnection, for usability. Attaching DERBY-5043 -2.diff and DERBY-5043 -2.zip, with these changes.
        Hide
        Rick Hillegas added a comment -

        Thanks, Kim. These changes look good. One small point in rrefattribderegister: Both the second and third bullets are instances of autoloading. Both of these patterns trigger the autoloading logic in DriverManager. The only difference between them is how DriverManager comes up with the list of drivers to autoload. The second bullet describes the original autoloading which was introduced by JDK 1.4. The third bullet describes an additional form of autoloading which was introduced by Java 6.

        Show
        Rick Hillegas added a comment - Thanks, Kim. These changes look good. One small point in rrefattribderegister: Both the second and third bullets are instances of autoloading. Both of these patterns trigger the autoloading logic in DriverManager. The only difference between them is how DriverManager comes up with the list of drivers to autoload. The second bullet describes the original autoloading which was introduced by JDK 1.4. The third bullet describes an additional form of autoloading which was introduced by Java 6.
        Hide
        Kim Haase added a comment -

        Thanks, Rick, that helped a very great deal. I have committed grand larceny on your contribution.

        Attaching DERBY-5043.diff, DERBY-5043.stat, and DERBY-5043.zip, with changes to the following files:

        A src/ref/rrefattribderegister.dita
        M src/ref/refderby.ditamap
        M src/ref/rrefattrib16471.dita

        I added a link to the deregister topic from the shutdown topic (rrefattrib16471.dita) as well as vice versa.

        I described the nondefault behavior first, as you did; I wonder if the default behavior should be described first?

        All corrections and other suggestions are welcome.

        Show
        Kim Haase added a comment - Thanks, Rick, that helped a very great deal. I have committed grand larceny on your contribution. Attaching DERBY-5043 .diff, DERBY-5043 .stat, and DERBY-5043 .zip, with changes to the following files: A src/ref/rrefattribderegister.dita M src/ref/refderby.ditamap M src/ref/rrefattrib16471.dita I added a link to the deregister topic from the shutdown topic (rrefattrib16471.dita) as well as vice versa. I described the nondefault behavior first, as you did; I wonder if the default behavior should be described first? All corrections and other suggestions are welcome.
        Hide
        Rick Hillegas added a comment - - edited

        > 2) Is this attribute valid only when using JDBC 4.0 or 4.1? (Driver autoloading is present with JDBC 4.0 but not with 3.0.)

        The attribute works if you are running on JDK 1.4 (i.e. JDBC 3.0). I don't think it is helpful to discuss this attribute in terms of autoloading. (In any event, driver autoloading was introduced by JDBC 3.0 although Derby didn't get around to supporting it until release 10.2.)

        I think it would be better to frame the discussion in terms of the following user-visible behaviors:

        1) Driver (de)registration.

        2) Orderly shutdown.

        3) Garbage-collection of Derby classes.

        There are several ways that the embedded driver can be registered:

        i) By invoking Class.forName( "org.apache.derby.jdbc.EmbeddedDriver" ). This mechanism works on all JVMs from JDK 1.4 on up.

        ii) By setting -Djdbc.drivers=org.apache.derby.jdbc.EmbeddedDriver when booting the engine's VM and then by calling DriverManager.getConnection(). This mechanism also works on all JVMs from JDK 1.4 on up. It is the original version of driver autoloading.

        iii) By simply calling DriverManager.getConnection(). This is the additional autoloading mechanism which was introduced by JDBC 4.0. This scenario only works on Java 6 on up.

        Once the embedded driver is registered, you can shutdown the Derby engine by using the special shutdown URL. If you specify deregister=false at the end of that URL, then you will see the following behavior:

        a) The embedded driver will remain registered.

        b) The Derby classes will NOT be garbage-collected.

        c) You can get a Derby connection just by issuing a DriverManager.getConnection() call. That is, you DON'T need to first invoke Class.forName( "org.apache.derby.jdbc.EmbeddedDriver" ).newInstance().

        In contrast, if you DON'T specify deregister=false on the shutdown URL, then you will see the opposite behavior:

        a) The embedded driver will be deregistered.

        b) The Derby classes will (probably, eventually) be garbage-collected.

        c) You will have to invoke Class.forName( "org.apache.derby.jdbc.EmbeddedDriver" ).newInstance(). before obtaining a new Derby connection.

        Hope this helps,
        -Rick

        Show
        Rick Hillegas added a comment - - edited > 2) Is this attribute valid only when using JDBC 4.0 or 4.1? (Driver autoloading is present with JDBC 4.0 but not with 3.0.) The attribute works if you are running on JDK 1.4 (i.e. JDBC 3.0). I don't think it is helpful to discuss this attribute in terms of autoloading. (In any event, driver autoloading was introduced by JDBC 3.0 although Derby didn't get around to supporting it until release 10.2.) I think it would be better to frame the discussion in terms of the following user-visible behaviors: 1) Driver (de)registration. 2) Orderly shutdown. 3) Garbage-collection of Derby classes. There are several ways that the embedded driver can be registered: i) By invoking Class.forName( "org.apache.derby.jdbc.EmbeddedDriver" ). This mechanism works on all JVMs from JDK 1.4 on up. ii) By setting -Djdbc.drivers=org.apache.derby.jdbc.EmbeddedDriver when booting the engine's VM and then by calling DriverManager.getConnection(). This mechanism also works on all JVMs from JDK 1.4 on up. It is the original version of driver autoloading. iii) By simply calling DriverManager.getConnection(). This is the additional autoloading mechanism which was introduced by JDBC 4.0. This scenario only works on Java 6 on up. Once the embedded driver is registered, you can shutdown the Derby engine by using the special shutdown URL. If you specify deregister=false at the end of that URL, then you will see the following behavior: a) The embedded driver will remain registered. b) The Derby classes will NOT be garbage-collected. c) You can get a Derby connection just by issuing a DriverManager.getConnection() call. That is, you DON'T need to first invoke Class.forName( "org.apache.derby.jdbc.EmbeddedDriver" ).newInstance(). In contrast, if you DON'T specify deregister=false on the shutdown URL, then you will see the opposite behavior: a) The embedded driver will be deregistered. b) The Derby classes will (probably, eventually) be garbage-collected. c) You will have to invoke Class.forName( "org.apache.derby.jdbc.EmbeddedDriver" ).newInstance(). before obtaining a new Derby connection. Hope this helps, -Rick
        Hide
        Kim Haase added a comment -

        Thanks, Lily, that helps a lot. I hope to have a patch for you to look at tomorrow.

        Show
        Kim Haase added a comment - Thanks, Lily, that helps a lot. I hope to have a patch for you to look at tomorrow.
        Hide
        Lily Wei added a comment -

        Thank you so much for looking at this issue, Kim. Please see my comments:

        1) The description at the top of DERBY-2905 says that after shutdown, the still-registered driver "does not support any future loading of connections," but the reply to Rick just now says that "When deregister=false, user can just obtain a new connection without issue Class.forName()." I thought the point of making true the default was that after a shutdown the driver could no longer be used, so it really needed to be deregistered. I admit I did not read the entire history of DERBY-2905, where this might be clarified.
        >>
        In the life of DERBY-2905, the nature of the fixed version change a little bit. I can see maybe I need two DERBY issues to address issue accordingly.
        It is true that when deregister=false, user can just obtain a new connection without issue Class.forName().
        However, when users shutdown Derby without specify deregister attribute, Derby will adopt deregister=true and unload the auto loaded driver. For users to obtain a new connection after that, they need to issue Class.forName() to avoid memory leak issue causing by having the auto loaded driver hanging around. It implies there will be no still-registered driver.
        During the discussion of implementing DERBY-2905, I think that is the desire behavior for Derby.

        2) Is this attribute valid only when using JDBC 4.0 or 4.1? (Driver autoloading is present with JDBC 4.0 but not with 3.0.)
        Yes, the attribute is valid for JDBC 4.0 and 4.1

        3) Does this attribute apply to the embedded driver only? Does it have any meaning if you are shutting down the network driver?
        The attribute is applied to embedded driver.

        Show
        Lily Wei added a comment - Thank you so much for looking at this issue, Kim. Please see my comments: 1) The description at the top of DERBY-2905 says that after shutdown, the still-registered driver "does not support any future loading of connections," but the reply to Rick just now says that "When deregister=false, user can just obtain a new connection without issue Class.forName()." I thought the point of making true the default was that after a shutdown the driver could no longer be used, so it really needed to be deregistered. I admit I did not read the entire history of DERBY-2905 , where this might be clarified. >> In the life of DERBY-2905 , the nature of the fixed version change a little bit. I can see maybe I need two DERBY issues to address issue accordingly. It is true that when deregister=false, user can just obtain a new connection without issue Class.forName(). However, when users shutdown Derby without specify deregister attribute, Derby will adopt deregister=true and unload the auto loaded driver. For users to obtain a new connection after that, they need to issue Class.forName() to avoid memory leak issue causing by having the auto loaded driver hanging around. It implies there will be no still-registered driver. During the discussion of implementing DERBY-2905 , I think that is the desire behavior for Derby. 2) Is this attribute valid only when using JDBC 4.0 or 4.1? (Driver autoloading is present with JDBC 4.0 but not with 3.0.) Yes, the attribute is valid for JDBC 4.0 and 4.1 3) Does this attribute apply to the embedded driver only? Does it have any meaning if you are shutting down the network driver? The attribute is applied to embedded driver.
        Hide
        Kim Haase added a comment -

        I have a few questions.

        1) The description at the top of DERBY-2905 says that after shutdown, the still-registered driver "does not support any future loading of connections," but the reply to Rick just now says that "When deregister=false, user can just obtain a new connection without issue Class.forName()." I thought the point of making true the default was that after a shutdown the driver could no longer be used, so it really needed to be deregistered. I admit I did not read the entire history of DERBY-2905, where this might be clarified.

        2) Is this attribute valid only when using JDBC 4.0 or 4.1? (Driver autoloading is present with JDBC 4.0 but not with 3.0.)

        3) Does this attribute apply to the embedded driver only? Does it have any meaning if you are shutting down the network driver?

        Show
        Kim Haase added a comment - I have a few questions. 1) The description at the top of DERBY-2905 says that after shutdown, the still-registered driver "does not support any future loading of connections," but the reply to Rick just now says that "When deregister=false, user can just obtain a new connection without issue Class.forName()." I thought the point of making true the default was that after a shutdown the driver could no longer be used, so it really needed to be deregistered. I admit I did not read the entire history of DERBY-2905 , where this might be clarified. 2) Is this attribute valid only when using JDBC 4.0 or 4.1? (Driver autoloading is present with JDBC 4.0 but not with 3.0.) 3) Does this attribute apply to the embedded driver only? Does it have any meaning if you are shutting down the network driver?
        Hide
        Rick Hillegas added a comment -

        Thanks Lily. I have verified that the behavior is as you describe. This looks good to me and will be helpful to users who do not want to make their connection logic aware of whether the engine was previously shutdown.

        Show
        Rick Hillegas added a comment - Thanks Lily. I have verified that the behavior is as you describe. This looks good to me and will be helpful to users who do not want to make their connection logic aware of whether the engine was previously shutdown.
        Hide
        Lily Wei added a comment -

        Thanks Rick. When deregister=true, user need to do either “new org.apache.derby.jdbc.EmbeddedDriver();” or “Class.forName(driver).newInstance();” in order to obtain a new connection. When deregister=false, user can just obtain a new connection without issue Class.forName(). The default behavior is deregister=true. I am also attaching Repro2905.java to reference easy test case.

        Show
        Lily Wei added a comment - Thanks Rick. When deregister=true, user need to do either “new org.apache.derby.jdbc.EmbeddedDriver();” or “Class.forName(driver).newInstance();” in order to obtain a new connection. When deregister=false, user can just obtain a new connection without issue Class.forName(). The default behavior is deregister=true. I am also attaching Repro2905.java to reference easy test case.
        Hide
        Rick Hillegas added a comment -

        What is the user-visible consequence of setting deregister=true? Does this mean that the user does not have to issue Class.forName() on the embedded driver class in order to obtain a new connection?

        Show
        Rick Hillegas added a comment - What is the user-visible consequence of setting deregister=true? Does this mean that the user does not have to issue Class.forName() on the embedded driver class in order to obtain a new connection?

          People

          • Assignee:
            Kim Haase
            Reporter:
            Lily Wei
          • Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development