Derby
  1. Derby
  2. DERBY-4978

Document the new SQLPermission required by the JDBC 4.1 Connection.abort(Executor) method

    Details

    • Type: Task Task
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.8.1.2
    • Fix Version/s: 10.8.1.2
    • Component/s: Documentation, JDBC
    • Labels:
      None

      Description

      We need to add material to the Reference and Developer's Guides as described in the 2011-01-14 comment on DERBY-4869.

      1. DERBY-4978.diff
        9 kB
        Kim Haase
      2. DERBY-4978.stat
        0.2 kB
        Kim Haase
      3. DERBY-4978.zip
        13 kB
        Kim Haase
      4. DERBY-4978-2.diff
        10 kB
        Kim Haase
      5. DERBY-4978-2.zip
        13 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Kim Haase added a comment -

          In order to complete this JIRA I probably need to at least start the basic infrastructure needed to document the JDBC 4.1 features in the Reference Manual – a section parallel to the "JDBC 4.0-only features" section in http://db.apache.org/derby/docs/dev/ref/.

          Is there any kind of overall list of the categories of JDBC 4.1 features akin to the one in http://db.apache.org/derby/docs/dev/ref/rrefjdbc4_0summary.html? If not, I can just start creating subsections – according to http://wiki.apache.org/db-derby/JdbcFourOne there are changes to the CallableStatement, Connection, DataBaseMetaData, PreparedStatement, ResultSet, and Statement interfaces.

          Show
          Kim Haase added a comment - In order to complete this JIRA I probably need to at least start the basic infrastructure needed to document the JDBC 4.1 features in the Reference Manual – a section parallel to the "JDBC 4.0-only features" section in http://db.apache.org/derby/docs/dev/ref/ . Is there any kind of overall list of the categories of JDBC 4.1 features akin to the one in http://db.apache.org/derby/docs/dev/ref/rrefjdbc4_0summary.html? If not, I can just start creating subsections – according to http://wiki.apache.org/db-derby/JdbcFourOne there are changes to the CallableStatement, Connection, DataBaseMetaData, PreparedStatement, ResultSet, and Statement interfaces.
          Hide
          Rick Hillegas added a comment -

          HI Kim. Thanks for picking up this issue. I don't know of any high level overview of the JDBC 4.1 changes similar to the 4.0 overview you cited. I think that the JDBC expert group plans to publish a spec update which will elaborate on what's in the JDK 7 javadoc. That spec update may supply the framework you need. You may want to contact spec lead Lance Andersen for his thoughts about how that spec update will be structured. Thanks.

          Show
          Rick Hillegas added a comment - HI Kim. Thanks for picking up this issue. I don't know of any high level overview of the JDBC 4.1 changes similar to the 4.0 overview you cited. I think that the JDBC expert group plans to publish a spec update which will elaborate on what's in the JDK 7 javadoc. That spec update may supply the framework you need. You may want to contact spec lead Lance Andersen for his thoughts about how that spec update will be structured. Thanks.
          Hide
          Kim Haase added a comment -

          Thanks, Rick. I'll get in touch with Lance, but there's no rush.

          In the meantime, would it be a decent start to say something like this in the "Granting permissions to Derby" (http://db.apache.org/derby/docs/dev/devguide/cdevbabejgjd.html) topic of the dev guide?

          permission java.sql.SQLPermission "callAbort";
          Allows Derby code to call the java.sql.Connection.abort method, if this permission is granted to derby.jar and derbyclient.jar. An application developer should take care to grant this permission only to Derby and to tools used by superusers.

          I am not sure what the "grant codebase" part of the policy would look like – this and what else? (I'm not sure it needs to be in the topic, but none of the example security policies show a grant to more than one file, so I am wondering if this is legal:

          grant codeBase "file://f:/derby/lib/derby.jar", "file://f:/derby/lib/derbyclient.jar" ...?

          I think it would be possible to do it like this – this would grant it to all the jar file in the library, though – would that be wrong?

          grant codeBase "file:$

          {derby.system.home}

          /lib/-" ... ?

          Show
          Kim Haase added a comment - Thanks, Rick. I'll get in touch with Lance, but there's no rush. In the meantime, would it be a decent start to say something like this in the "Granting permissions to Derby" ( http://db.apache.org/derby/docs/dev/devguide/cdevbabejgjd.html ) topic of the dev guide? permission java.sql.SQLPermission "callAbort"; Allows Derby code to call the java.sql.Connection.abort method, if this permission is granted to derby.jar and derbyclient.jar. An application developer should take care to grant this permission only to Derby and to tools used by superusers. I am not sure what the "grant codebase" part of the policy would look like – this and what else? (I'm not sure it needs to be in the topic, but none of the example security policies show a grant to more than one file, so I am wondering if this is legal: grant codeBase "file://f:/derby/lib/derby.jar", "file://f:/derby/lib/derbyclient.jar" ...? I think it would be possible to do it like this – this would grant it to all the jar file in the library, though – would that be wrong? grant codeBase "file:$ {derby.system.home} /lib/-" ... ?
          Hide
          Rick Hillegas added a comment -

          Hi Kim,

          The blurb on "callAbort" looks good to me.

          The existing policy files have a number of grant blocks. Each block grants a lump of permissions to a single jar file. I think that is a good pattern which makes the policy files easy to read. You can see at a glance what permissions are granted to each code domain. I would not recommend trying to grant a permission to multiple code domains all at once. I think that would be harder for tech support to understand.

          Thanks,
          -Rick

          Show
          Rick Hillegas added a comment - Hi Kim, The blurb on "callAbort" looks good to me. The existing policy files have a number of grant blocks. Each block grants a lump of permissions to a single jar file. I think that is a good pattern which makes the policy files easy to read. You can see at a glance what permissions are granted to each code domain. I would not recommend trying to grant a permission to multiple code domains all at once. I think that would be harder for tech support to understand. Thanks, -Rick
          Hide
          Kim Haase added a comment -

          Thanks, Rick, I'll go with that writeup, then.

          By "the existing policy files" I guess you mean our example ones. So people could grant one set of permissions to derby.jar, another set to derbyclient.jar, and so on.

          The GlassFish policy file gives blanket permissions to all the jars, but I guess that makes sense for the app server (as opposed to a user application):

          // Derby driver classes get all permissions by default
          grant codeBase "file:$

          {com.sun.aas.derbyRoot}

          /lib/-"

          { permission java.security.AllPermission; }

          ;

          Show
          Kim Haase added a comment - Thanks, Rick, I'll go with that writeup, then. By "the existing policy files" I guess you mean our example ones. So people could grant one set of permissions to derby.jar, another set to derbyclient.jar, and so on. The GlassFish policy file gives blanket permissions to all the jars, but I guess that makes sense for the app server (as opposed to a user application): // Derby driver classes get all permissions by default grant codeBase "file:$ {com.sun.aas.derbyRoot} /lib/-" { permission java.security.AllPermission; } ;
          Hide
          Rick Hillegas added a comment -

          Ouch. That's a pretty scary policy for Derby. I assume people know what they are doing. Thanks.

          Show
          Rick Hillegas added a comment - Ouch. That's a pretty scary policy for Derby. I assume people know what they are doing. Thanks.
          Hide
          Kim Haase added a comment -

          Lance says, "There will be an MR, which is just a change log as we get closer to Java SE 7 going out. This is a small update to JDBC. The features are all minor API changes which the javadocs, which are part of the spec, document."

          He thinks that a general overview is not needed. We can just describe the API changes.

          Show
          Kim Haase added a comment - Lance says, "There will be an MR, which is just a change log as we get closer to Java SE 7 going out. This is a small update to JDBC. The features are all minor API changes which the javadocs, which are part of the spec, document." He thinks that a general overview is not needed. We can just describe the API changes.
          Hide
          Kim Haase added a comment -

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

          M src/devguide/cdevcbabejdfj.dita
          M src/devguide/cdevbabejgjd.dita
          M src/ref/rrefjdbc4_0summary.dita
          A src/ref/rrefjdbc4_1summary.dita
          A src/ref/rrefjdbc4_1connection.dita
          M src/ref/refderby.ditamap

          cdevcbabejdfj.dita (Running Derby under a security manager): corrected index entry, URL

          cdevbabejgjd.dita (Granting permissions to Derby): corrected URL, changed "Derby" to conrefs name, added entry for callAbort permission

          rrefjdbc4_0summary.dita (was JDBC 4.0-only features): updated title to include 4.1, added index entry and mention of JDBC 4.1

          rrefjdbc4_1summary.dita (JDBC 4.1-only features): New file

          rrefjdbc4_1connection.dita (java.sql.Connection interface: JDBC 4.1 features): New file listing abort method; left "features" in plural since more are coming, I think

          refderby.ditamap: added new files, edited title of rrefjdbc4_0summary.dita

          It looks as if several more of the items in http://wiki.apache.org/db-derby/JdbcFourOne have been implemented, so if you want to file doc issues for them, please go ahead.

          Show
          Kim Haase added a comment - Attaching DERBY-4978 .diff, DERBY-4978 .stat, and DERBY-4978 .zip, with changes to the following files: M src/devguide/cdevcbabejdfj.dita M src/devguide/cdevbabejgjd.dita M src/ref/rrefjdbc4_0summary.dita A src/ref/rrefjdbc4_1summary.dita A src/ref/rrefjdbc4_1connection.dita M src/ref/refderby.ditamap cdevcbabejdfj.dita (Running Derby under a security manager): corrected index entry, URL cdevbabejgjd.dita (Granting permissions to Derby): corrected URL, changed "Derby" to conrefs name, added entry for callAbort permission rrefjdbc4_0summary.dita (was JDBC 4.0-only features): updated title to include 4.1, added index entry and mention of JDBC 4.1 rrefjdbc4_1summary.dita (JDBC 4.1-only features): New file rrefjdbc4_1connection.dita (java.sql.Connection interface: JDBC 4.1 features): New file listing abort method; left "features" in plural since more are coming, I think refderby.ditamap: added new files, edited title of rrefjdbc4_0summary.dita It looks as if several more of the items in http://wiki.apache.org/db-derby/JdbcFourOne have been implemented, so if you want to file doc issues for them, please go ahead.
          Hide
          Rick Hillegas added a comment -

          Thanks, Kim. These changes look good. I have a couple comments:

          cdevbabejgjd:

          I think that the reader might be confused about whether this permission should be granted to the derby jars or to application code. It's certainly a point which confused me for a while. The permission needs to be granted to both--but the user just needs to be careful to not blanket-grant it to all application code.

          rrefjdbc4_1connection.html

          I would make the same points about what code gets this permission. In addition, I would recommend adding a little more explanation of what this method does. Something like this:

          "The abort(Executor) method aborts a running connection. Outstanding transactional work is rolled back and the physical connection to the database is destroyed. When running under a Java SecurityManager, this method can be called only if SQLPermission( "callAbort" ) has been granted both to the Derby JDBC driver (in derby.jar and derbyclient.jar) and to the user code which calls Connection.abort(). For security reasons, permission to execute this method should not be granted lightly. Do not grant this permission to application code unless you are certain it can only be invoked by superusers. For more information, see "Granting permissions to Derby" in Derby Developer's Guide."

          Show
          Rick Hillegas added a comment - Thanks, Kim. These changes look good. I have a couple comments: cdevbabejgjd: I think that the reader might be confused about whether this permission should be granted to the derby jars or to application code. It's certainly a point which confused me for a while. The permission needs to be granted to both--but the user just needs to be careful to not blanket-grant it to all application code. rrefjdbc4_1connection.html I would make the same points about what code gets this permission. In addition, I would recommend adding a little more explanation of what this method does. Something like this: "The abort(Executor) method aborts a running connection. Outstanding transactional work is rolled back and the physical connection to the database is destroyed. When running under a Java SecurityManager, this method can be called only if SQLPermission( "callAbort" ) has been granted both to the Derby JDBC driver (in derby.jar and derbyclient.jar) and to the user code which calls Connection.abort(). For security reasons, permission to execute this method should not be granted lightly. Do not grant this permission to application code unless you are certain it can only be invoked by superusers. For more information, see "Granting permissions to Derby" in Derby Developer's Guide."
          Hide
          Kim Haase added a comment -

          Thanks very much, Rick. Attaching a second patch (DERBY-4978-2.diff, DERBY-4978-2.zip) that I hope addresses your comments. Please let me know if more fixes are needed.

          Show
          Kim Haase added a comment - Thanks very much, Rick. Attaching a second patch ( DERBY-4978 -2.diff, DERBY-4978 -2.zip) that I hope addresses your comments. Please let me know if more fixes are needed.
          Hide
          Rick Hillegas added a comment -

          Thanks, Kim. Looks great. +1.

          Show
          Rick Hillegas added a comment - Thanks, Kim. Looks great. +1.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-4978-2.diff to documentation trunk at revision 1064226.

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

          Changes appeared in 10.8.1 documentation, so closing.

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

            People

            • Assignee:
              Kim Haase
              Reporter:
              Rick Hillegas
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development