You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by ch...@apache.org on 2009/01/05 20:50:48 UTC
svn commit: r731664 [1/2] - in /db/derby/docs/trunk/src: devguide/ ref/
tools/
Author: chaase3
Date: Mon Jan 5 11:50:47 2009
New Revision: 731664
URL: http://svn.apache.org/viewvc?rev=731664&view=rev
Log:
DERBY-3193: SQL roles: Add documentation
This patch contains most of the changes to the Reference Manual, Developer's Guide, and Tools Guide required to document SQL roles. A smaller patch with a few additional changes will follow.
Patch: DERBY-3193-3.diff
Added:
db/derby/docs/trunk/src/devguide/cdevcsecureroles.dita (with props)
db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthexceptions.dita (with props)
db/derby/docs/trunk/src/ref/rrefcreaterole.dita (with props)
db/derby/docs/trunk/src/ref/rrefcurrentrole.dita (with props)
db/derby/docs/trunk/src/ref/rrefdroprole.dita (with props)
db/derby/docs/trunk/src/ref/rrefrolename.dita (with props)
db/derby/docs/trunk/src/ref/rrefsetrole.dita (with props)
db/derby/docs/trunk/src/ref/rrefsistabssysroles.dita (with props)
Modified:
db/derby/docs/trunk/src/devguide/cdevcsecure36595.dita
db/derby/docs/trunk/src/devguide/cdevcsecure865880.dita
db/derby/docs/trunk/src/devguide/cdevcsecure866060.dita
db/derby/docs/trunk/src/devguide/cdevcsecuregrantrevokeaccess.dita
db/derby/docs/trunk/src/devguide/derbydev.ditamap
db/derby/docs/trunk/src/devguide/rdevcsecure190.dita
db/derby/docs/trunk/src/devguide/rdevcsecure379.dita
db/derby/docs/trunk/src/ref/crefsqlj35312.dita
db/derby/docs/trunk/src/ref/crefsqlj80721.dita
db/derby/docs/trunk/src/ref/crefsqlj95081.dita
db/derby/docs/trunk/src/ref/refderby.ditamap
db/derby/docs/trunk/src/ref/rrefsistabssyscolperms.dita
db/derby/docs/trunk/src/ref/rrefsistabssysroutineperms.dita
db/derby/docs/trunk/src/ref/rrefsistabssystableperms.dita
db/derby/docs/trunk/src/ref/rrefsqlj30540.dita
db/derby/docs/trunk/src/ref/rrefsqlj31580.dita
db/derby/docs/trunk/src/ref/rrefsqljgrant.dita
db/derby/docs/trunk/src/ref/rrefsqljrevoke.dita
db/derby/docs/trunk/src/ref/rrefsyscsdiagtables.dita
db/derby/docs/trunk/src/tools/rtoolsijcomrefshow.dita
Modified: db/derby/docs/trunk/src/devguide/cdevcsecure36595.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecure36595.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecure36595.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcsecure36595.dita Mon Jan 5 11:50:47 2009
@@ -54,6 +54,9 @@
to the database. If you do not explicitly set the <codeph>derby.database.defaultConnectionMode</codeph> property,
the default user authorization for a database is <varname>fullAccess</varname>,
which is read-write access.</li>
+<li>The <codeph>derby.database.fullAccessUsers</codeph> and <codeph>derby.database.readOnlyAccessUsers</codeph> properties
+are user specific properties. Use these properties to specify the user IDs
+that have read-write access and read-only access to a database.</li>
<li>The <codeph>derby.database.sqlAuthorization</codeph> property enables
SQL standard authorization. Use the <codeph>derby.database.sqlAuthorization</codeph> property
to specify if object owners can grant and revoke permission for users to perform
@@ -62,9 +65,6 @@
is set to <varname>TRUE</varname>, object owners can use the GRANT and REVOKE
SQL statements to set the user permissions for specific database objects or
for specific SQL actions. </li>
-<li>The <codeph>derby.database.fullAccessUsers</codeph> and <codeph>derby.database.readOnlyAccessUsers</codeph> properties
-are user specific properties. Use these properties to specify the user IDs
-that have read-write access and read-only access to a database.</li>
</ul></p>
<p>If you do not specify the user authorizations for a specific user ID, the
user ID inherits whatever authorization is set as the default user authorization
Modified: db/derby/docs/trunk/src/devguide/cdevcsecure865880.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecure865880.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecure865880.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcsecure865880.dita Mon Jan 5 11:50:47 2009
@@ -19,7 +19,7 @@
limitations under the License.
-->
<concept id="cdevcsecure865880" xml:lang="en-us">
-<title>Setting the user authorizations for individual users</title>
+<title>Setting access for individual users</title>
<shortdesc>Use the <codeph>derby.database.fullAccessUsers</codeph> and <codeph>derby.database.readOnlyAccessUsers</codeph> properties
to specify the user IDs that have read-write access and read-only access to
a database.</shortdesc>
Modified: db/derby/docs/trunk/src/devguide/cdevcsecure866060.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecure866060.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecure866060.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcsecure866060.dita Mon Jan 5 11:50:47 2009
@@ -29,13 +29,18 @@
<conbody>
<p>The <codeph>derby.database.sqlAuthorization</codeph> property controls
the ability for object owners to grant and revoke permission for users to
-perform actions on database objects. </p>
+perform actions on database objects. It also controls the ability for users
+to create, set, and drop roles.</p>
<p>The valid settings for the <codeph>derby.database.sqlAuthorization</codeph> property
-are:<ul>
+are:</p><ul>
<li><varname>TRUE</varname></li>
<li><varname>FALSE</varname></li>
-</ul>The default setting for the <codeph>derby.database.sqlAuthorization</codeph> property
+</ul><p>The default setting for the <codeph>derby.database.sqlAuthorization</codeph> property
is <varname>FALSE</varname>.</p>
+<p>The <codeph>derby.database.sqlAuthorization</codeph> property is usable only
+if the property <codeph>derby.connection.requireAuthentication</codeph> is also
+set to true, since SQL authorization is of no value unless authentication is
+also enabled.</p>
<p>After you set the <codeph>derby.database.sqlAuthorization</codeph> property
to <varname>TRUE</varname>, you cannot set the property back to <varname>FALSE</varname>.</p>
<p>You can set the <codeph>derby.database.sqlAuthorization</codeph> property
@@ -44,7 +49,7 @@
automatically have SQL authorization enabled. If the databases already exists,
you can set this property only as a database property.</p>
<p>To enable SQL standard authorization for the entire system, set the <codeph>derby.database.sqlAuthorization</codeph> property
-as a system property:<codeblock><b>derby.database.sqlAuthorization=true</b></codeblock></p>
+as a system property:</p><codeblock><b>derby.database.sqlAuthorization=true</b></codeblock>
<p>To enable SQL standard authorization for a specific database, set the <codeph>derby.database.sqlAuthorization</codeph> property
as a database property:</p>
<codeblock>CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY(
Modified: db/derby/docs/trunk/src/devguide/cdevcsecuregrantrevokeaccess.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecuregrantrevokeaccess.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecuregrantrevokeaccess.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevcsecuregrantrevokeaccess.dita Mon Jan 5 11:50:47 2009
@@ -19,13 +19,14 @@
limitations under the License.
-->
<concept id="cdevcsecuregrantrevokeaccess" xml:lang="en-us">
-<title>SQL standard authorization</title>
+<title>Using SQL standard authorization</title>
<shortdesc>When the SQL standard authorization mode is enabled, object owners
can use the GRANT and REVOKE SQL statements to set the user permissions for
-specific database objects or for specific SQL actions.</shortdesc>
+specific database objects or for specific SQL actions. They can also use roles
+to administer privileges.</shortdesc>
<prolog><metadata>
-<keywords><indexterm>user authorizations<indexterm>grant</indexterm></indexterm>
-<indexterm>user authorizations<indexterm>revoke</indexterm></indexterm><indexterm>user
+<keywords><indexterm>user authorizations<indexterm>granting</indexterm></indexterm>
+<indexterm>user authorizations<indexterm>revoking</indexterm></indexterm><indexterm>user
authorizations<indexterm>PUBLIC</indexterm></indexterm><indexterm>GRANT statement<indexterm>overview</indexterm></indexterm>
<indexterm>REVOKE statement<indexterm>overview</indexterm></indexterm><indexterm>access
control system<indexterm>SQL2003</indexterm></indexterm><indexterm>SQL standard
@@ -43,9 +44,10 @@
conref="../conrefs.dita#prod/productshortname"></ph> SQL authorization mode
provides a more precise mechanism to limit the actions that users can take
on the database.</p>
-<p>The GRANT statement is used to grant specific permissions to users. The
-REVOKE statement is used to revoke permissions. The grant and revoke privileges
-are:<ul>
+<p>The GRANT statement is used to grant specific permissions to users or to
+roles, or to grant roles to users or to roles. The
+REVOKE statement is used to revoke permissions and role grants. The grant and
+revoke privileges are:<ul>
<li>DELETE</li>
<li>EXECUTE</li>
<li>INSERT</li>
@@ -62,16 +64,17 @@
No other users have privileges on the object until the object owner grants
privileges to them.</p>
<section><title>Public and individual user privileges</title><p>The object
-owner can grant and revoke privileges for specific users or for all users.
+owner can grant and revoke privileges for specific users, for specific roles,
+or for all users.
The keyword PUBLIC is used to specify all users. When PUBLIC is specified,
the privileges affect all current and future users. The privileges granted
-and revoked to PUBLIC and to individual users are independent. For example,
+and revoked to PUBLIC and to individual users or roles are independent. For example,
a SELECT privilege on table <codeph>t</codeph> is granted to both PUBLIC and
to the user <codeph>harry</codeph>. The SELECT privilege is later revoked
from user <codeph>harry</codeph>, but user <codeph>harry</codeph> has access
to table <codeph>t</codeph> through the PUBLIC privilege.</p><note othertype="Exception"
type="other">When you create a view, trigger, or constraint, <ph conref="../conrefs.dita#prod/productshortname"></ph> first
-checks to determine if you have the required privileges at the user-level.
+checks to determine if you have the required privileges at the user level.
If you have the user-level privileges, the object is created and is dependent
on that user-level privilege. If you do not have the required privileges at
the user-level, <ph conref="../conrefs.dita#prod/productshortname"></ph> checks
@@ -138,7 +141,7 @@
those permissions to perform actions on a view, trigger, or constraint. </p><p>If
the required permissions are revoked from the owner of a view, trigger, or
constraint, the object is dropped as part of the REVOKE statement.</p><p>See
-the <cite><ph conref="../conrefs.dita#pub/citref"></ph></cite> for more information
-on the GRANT and REVOKE statements.</p></section>
+the <cite><ph conref="../conrefs.dita#pub/citref"></ph></cite> for more
+information on the GRANT and REVOKE statements.</p></section>
</conbody>
</concept>
Added: db/derby/docs/trunk/src/devguide/cdevcsecureroles.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevcsecureroles.dita?rev=731664&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevcsecureroles.dita (added)
+++ db/derby/docs/trunk/src/devguide/cdevcsecureroles.dita Mon Jan 5 11:50:47 2009
@@ -0,0 +1,189 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "concept.dtd">
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<concept id="cdevcsecureroles" xml:lang="en-us">
+<title>Using SQL roles</title>
+<shortdesc>When the SQL standard authorization mode is enabled, object owners
+can use the SQL roles facility to administer privileges.</shortdesc>
+<prolog><metadata>
+<keywords>
+<indexterm>access control system<indexterm>SQL2003</indexterm></indexterm>
+<indexterm>SQL standard authorization mode<indexterm>SQL roles</indexterm></indexterm>
+<indexterm>SQL roles<indexterm>using</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<conbody>
+<p>SQL roles are useful for administering privileges when a database has many
+users. Roles provide a more powerful way to grant privileges to users' sessions
+than to grant privileges to each user of the database, which easily becomes
+tedious and error-prone when many users are involved. Roles do not in and of
+themselves give better database security, but used correctly, they facilitate
+better security. Only the
+<xref href="cdevcsecureDbOwner.dita#cdevcsecureDbOwner">database owner</xref>
+can create, grant, revoke, and drop roles. However, object owners can grant and
+revoke privileges for those objects to and from roles, as well as to and from
+individual users and PUBLIC (all users).</p>
+<note><ph conref="../conrefs.dita#prod/productshortname"></ph> implements a
+subset of SQL roles. The fact that only the database owner can create, grant,
+revoke, and drop roles is an implementation restriction.</note>
+<section id="rolecreategrant"><title>Creating and granting roles</title>
+<p>Roles are available only when SQL authorization mode is enabled (that is,
+when the property <codeph>derby.database.sqlAuthorization</codeph> is set to
+<codeph>TRUE</codeph>).</p>
+<p>Old databases must be (hard) upgraded to at least Release 10.5 before roles
+can be used.</p>
+<p>If SQL authorization mode is enabled, the database owner can use the
+CREATE ROLE statement to create roles. The database owner can then use the GRANT
+statement to grant a role to one or more users, to PUBLIC, or to another role.
+</p>
+<p>A role A <i>contains</i> another role B if role B is granted to role A, or is
+contained in a role granted to role A. In this case, the privileges identified
+by role B are inherited by role A.</p>
+<p>For example, suppose the database owner issued the following statements:</p>
+<codeblock> create role readUser;
+ create role updateUser;
+ create role taskLeaderA;
+ create role taskLeaderB;
+ create role projectLeader;
+ grant readUser to updateUser;
+ grant updateUser to taskLeaderA;
+ grant updateUser to taskLeaderB;
+ grant taskLeaderA to projectLeader;
+ grant taskLeaderB to projectLeader;
+</codeblock>
+<p>The roles would then have the following containment relationships:</p>
+<codeblock> readUser
+ |
+ v
+ updateUser
+ / \
+ taskLeaderA taskLeaderB
+ \ /
+ projectLeader
+</codeblock>
+<p>In this case, the <codeph>projectLeader</codeph> role contains all the other
+roles and has all their privileges. If the database owner then revokes
+<codeph>updateUser</codeph> from <codeph>taskLeaderA</codeph>,
+<codeph>projectLeader</codeph> still contains that role through
+<codeph>taskLeaderB</codeph>.</p>
+<p>The SYSCS_DIAG.CONTAINED_ROLES diagnostic table function can be used to
+determine the set of contained roles for a role.</p>
+<p>Cycles are not permitted in role grants. That is, if a role contains another
+role, you cannot grant the container role to the contained role. For example,
+the following statement would not be permitted:</p>
+<codeblock>grant projectLeader to updateUser;</codeblock>
+</section>
+<section><title>Setting roles</title>
+<p>When you first connect to
+<ph conref="../conrefs.dita#prod/productshortname"></ph>, no role is set, and
+the CURRENT_ROLE function returns null. During a session, you can call the SET
+ROLE statement to set the current role for that session. The role you set can be
+any role that has been granted to the session's current user or to PUBLIC. To
+unset the current role, call SET ROLE with an argument of NONE. At any time
+during a session, there is always a current user, but there is a current role
+only if SET ROLE has been called with an argument other than NONE. If a current
+role is not set, the session has only the privileges granted to you directly or
+to PUBLIC.</p>
+<p>To retrieve the current role identifier in SQL, call the CURRENT_ROLE
+function.</p>
+<p>Within stored procedures and functions that contain SQL, the current role is
+on the authorization stack. Initially, inside a nested connection, the current
+role is set to that of the calling context. Upon return from the stored
+procedure or function, the authorization stack is popped, so the current role
+of the calling context is not affected by any setting of the role inside the
+called procedure or function. If the stored procedure opens more than one
+nested connection, these all share the same (stacked) current role state. Any
+dynamic result set passed out of a stored procedure sees the current role of
+the nested context.</p>
+</section>
+<section><title>Granting privileges to roles</title>
+<p>Once a role has been created, both the database owner and the object owner
+can grant privileges on tables and routines to that role. You can grant the same
+privileges to roles that you can grant to users. Granting a privilege to a role
+implicitly grants privileges to all roles that contain that role. For example,
+if you grant delete privileges on a table to <codeph>updateUser</codeph>, every
+user in the <codeph>updateUser</codeph>, <codeph>taskLeaderA</codeph>,
+<codeph>taskLeaderB</codeph>, and <codeph>projectLeader</codeph> role will also
+have delete privileges on that table, but users in the <codeph>readUser</codeph>
+role will not.</p>
+</section>
+<section><title>Revoking privileges from a role</title>
+<p>Either the database owner or the object owner can revoke privileges from a
+role.</p>
+<p>When a privilege is revoked from a role A, that privilege is no longer held
+by role A, unless A otherwise inherits that privilege from a contained role.</p>
+<p>If a role loses a privilege to an object, and a session whose current user is
+different from the owner of that object has a current role which is that role
+or a role that contains that role, the session also loses that privilege,
+unless one or more of the following is true:</p>
+<ul>
+<li>The role is granted directly to the current user</li>
+<li>The role is granted to PUBLIC</li>
+<li>The role is also granted to another role in the current role's contained
+roles</li>
+<li>The session's current user is the database owner</li>
+</ul>
+</section>
+<section><title>Revoking roles</title>
+<p>The database owner can use the REVOKE statement to revoke a role from a user
+or from another role.</p>
+<p>When a role is revoked from a user, that session can no longer keep that
+role, nor can it take on that role in a SET ROLE statement, unless the role is
+also granted to PUBLIC. If that role is the current role of an existing session,
+the current privileges of the session lose any extra privileges obtained through
+setting that role.</p>
+<p>The default drop behavior is CASCADE. Therefore, all persistent objects
+(constraints, views and triggers) that rely on that role are dropped. Although
+there may be other ways of fulfilling that privilege at the time of the revoke,
+any dependent objects are still dropped. This is an implementation limitation.
+Any prepared statement that is potentially affected will be checked again on the
+next execute. A result set that depends on a role will remain open even if that
+role is revoked from a user.</p>
+<p>When a role is revoked from a role, the default drop behavior is also
+CASCADE. Suppose you revoke role A from role B. Revoking the role will have the
+effect of revoking all additional applicable privileges obtained through A from
+B. Roles that contain B will also lose those privileges, unless A is still
+contained in some other role C granted to B, or the privileges come through some
+other role. See
+<xref href="cdevcsecureroles.dita#cdevcsecureroles/rolecreategrant"></xref>
+for an example.</p>
+</section>
+<section><title>Dropping roles</title>
+<p>Only the database owner can drop a role. To drop a role, use the DROP ROLE
+statement.</p>
+<p>Dropping a role effectively revokes all grants of this role to users and
+other roles.</p>
+</section>
+<section><title>Further information</title>
+<p>For details on the following statements, functions, and system table related
+to roles, see the <ph conref="../conrefs.dita#pub/citref"></ph>.
+<ul>
+<li>CREATE ROLE statement</li>
+<li>SET ROLE statement</li>
+<li>DROP ROLE statement</li>
+<li>GRANT statement</li>
+<li>REVOKE statement</li>
+<li>CURRENT_ROLE function</li>
+<li>SYSCS_DIAG.CONTAINED_ROLES table function</li>
+<li>SYSROLES system table</li>
+</ul></p>
+</section>
+</conbody>
+</concept>
Propchange: db/derby/docs/trunk/src/devguide/cdevcsecureroles.dita
------------------------------------------------------------------------------
svn:eol-style = native
Modified: db/derby/docs/trunk/src/devguide/derbydev.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/derbydev.ditamap?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/derbydev.ditamap (original)
+++ db/derby/docs/trunk/src/devguide/derbydev.ditamap Mon Jan 5 11:50:47 2009
@@ -1499,73 +1499,6 @@
</relrow>
<relrow>
<relcell>
-<topicref href="cdevcsecure865818.dita" navtitle="Setting the default connection access mode">
-</topicref>
-</relcell>
-<relcell>
-<topicref href="cdevcsecure865880.dita" navtitle="Setting the user authorizations for individual users">
-</topicref>
-<topicref href="cdevcsecure865880.dita" navtitle="Setting the user authorizations for individual users">
-</topicref>
-<topicref href="cdevcsecuregrantrevokeaccess.dita" navtitle="SQL standard authorization">
-</topicref>
-<topicref href="rdevcsecure379.dita" navtitle="User authorization exceptions">
-</topicref>
-</relcell>
-</relrow>
-<relrow>
-<relcell>
-<topicref href="cdevcsecure865880.dita" navtitle="Setting the user authorizations for individual users">
-</topicref>
-</relcell>
-<relcell>
-<topicref href="cdevcsecure865818.dita" navtitle="Setting the default connection access mode">
-</topicref>
-<topicref href="cdevcsecure865880.dita" navtitle="Setting the user authorizations for individual users">
-</topicref>
-<topicref href="rdevcsecure379.dita" navtitle="User authorization exceptions">
-</topicref>
-</relcell>
-</relrow>
-<relrow>
-<relcell>
-<topicref href="cdevcsecure866060.dita" navtitle="Setting the SQL standard authorization mode">
-</topicref>
-</relcell>
-<relcell>
-<topicref href="cdevcsecuregrantrevokeaccess.dita" navtitle="SQL standard authorization">
-</topicref>
-<topicref href="rdevcsecure190.dita" navtitle="Read-only and full access permissions">
-</topicref>
-<topicref href="rdevcsecure379.dita" navtitle="User authorization exceptions">
-</topicref>
-</relcell>
-</relrow>
-<relrow>
-<relcell>
-<topicref href="rdevcsecure190.dita" navtitle="Read-only and full access permissions">
-</topicref>
-</relcell>
-<relcell>
-<topicref href="cdevcsecuregrantrevokeaccess.dita" navtitle="SQL standard authorization">
-</topicref>
-</relcell>
-</relrow>
-<relrow>
-<relcell>
-<topicref href="cdevcsecuregrantrevokeaccess.dita" navtitle="SQL standard authorization">
-</topicref>
-</relcell>
-<relcell>
-<topicref href="cdevcsecure866060.dita" navtitle="Setting the SQL standard authorization mode">
-</topicref>
-<topicref href="../ref/rrefsqljgrant.dita" navtitle="GRANT statement "></topicref>
-<topicref href="../ref/rrefsqljrevoke.dita" navtitle="REVOKE statement ">
-</topicref>
-</relcell>
-</relrow>
-<relrow>
-<relcell>
<topicref href="cdevcsecure88690.dita" navtitle="Encrypting databases on creation">
</topicref>
</relcell>
@@ -2207,18 +2140,16 @@
<topicref href="rdevcsecure622.dita" navtitle="Exceptions when using authorization identifiers">
</topicref>
</topicref>
-<topicref href="cdevcsecure36595.dita" navtitle="User authorization">
-<topicref href="cdevcsecure866060.dita" navtitle="Setting user authorization">
-<topicref href="cdevcsecure865818.dita" navtitle="Setting the default access mode">
-<topicref href="cdevcsecure865880.dita" navtitle="Setting the access mode for particular users">
-</topicref>
-</topicref>
-<topicref href="cdevcsecuregrantrevokeaccess.dita" navtitle="Grant and revoke access control">
-</topicref>
-<topicref href="rdevcsecure379.dita" navtitle="User authorization exceptions">
-</topicref>
-</topicref>
-<topicref href="rdevcsecure190.dita" navtitle="Read-only and full access permissions">
+<topicref collection-type="family" href="cdevcsecure36595.dita" navtitle="User authorizations">
+<topicref href="cdevcsecure865818.dita" navtitle="Setting the default connection access mode"></topicref>
+<topicref collection-type="family" href="cdevcsecure865880.dita" navtitle="Setting access for individual users">
+<topicref href="rdevcsecure190.dita" navtitle="Read-only and full access permissions"></topicref>
+<topicref href="rdevcsecure379.dita" navtitle="User authorization exceptions"></topicref>
+</topicref>
+<topicref collection-type="family" href="cdevcsecure866060.dita" navtitle="Setting the SQL standard authorization mode">
+<topicref href="cdevcsecuregrantrevokeaccess.dita" navtitle="Using SQL standard authorization"></topicref>
+<topicref href="cdevcsecureroles.dita" navtitle="Using SQL roles"></topicref>
+<topicref href="rdevcsecuresqlauthexceptions.dita" navtitle="SQL standard authorization exceptions"></topicref>
</topicref>
</topicref>
<topicref href="cdevcsecure24366.dita" navtitle="Encrypting databases on disk">
Modified: db/derby/docs/trunk/src/devguide/rdevcsecure190.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevcsecure190.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevcsecure190.dita (original)
+++ db/derby/docs/trunk/src/devguide/rdevcsecure190.dita Mon Jan 5 11:50:47 2009
@@ -60,22 +60,22 @@
</row>
<row>
<entry colname="1">Executing INSERT, UPDATE, or DELETE statements</entry>
-<entry colname="2"></entry>
+<entry colname="2"> </entry>
<entry colname="3">X</entry>
</row>
<row>
<entry colname="1">Executing DDL statements</entry>
-<entry colname="2"></entry>
+<entry colname="2"> </entry>
<entry colname="3">X</entry>
</row>
<row>
<entry colname="1">Adding or replacing jar files</entry>
-<entry colname="2"></entry>
+<entry colname="2"> </entry>
<entry colname="3">X</entry>
</row>
<row>
<entry colname="1">Setting database properties</entry>
-<entry colname="2"></entry>
+<entry colname="2"> </entry>
<entry colname="3">X</entry>
</row>
</tbody>
Modified: db/derby/docs/trunk/src/devguide/rdevcsecure379.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevcsecure379.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevcsecure379.dita (original)
+++ db/derby/docs/trunk/src/devguide/rdevcsecure379.dita Mon Jan 5 11:50:47 2009
@@ -28,9 +28,8 @@
<refbody>
<section><p><ph conref="../conrefs.dita#prod/productshortname"></ph> validates
the database properties when you set the properties. An exception is returned
-if you specify an invalid value when you set these properties. </p><p>After
-you set the <codeph>derby.database.sqlAuthorization</codeph> property to <varname>TRUE</varname>,
-you cannot set the property back to <varname>FALSE</varname>.</p><p>If a user
+if you specify an invalid value when you set these properties. </p>
+<p>If a user
attempts to connect to a database but is not authorized to connect to that
database, the SQLException 04501 is returned. </p><p>If a user with read-only
access attempts to write to a database, the SQLException 08004 <codeph>- connection
Added: db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthexceptions.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthexceptions.dita?rev=731664&view=auto
==============================================================================
--- db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthexceptions.dita (added)
+++ db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthexceptions.dita Mon Jan 5 11:50:47 2009
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<reference id="rdevcsecuresqlauthexceptions" xml:lang="en-us">
+<title>SQL standard authorization exceptions</title>
+<shortdesc>SQL exceptions are returned when errors occur with SQL
+authorization.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>SQL exceptions<indexterm>SQL authorization</indexterm></indexterm>
+<indexterm>SQL authorization<indexterm>SQL exceptions</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section>
+<p>The following errors can result from the CREATE ROLE statement:</p>
+<ul>
+<li>You cannot create a role if you are not the database owner. An attempt to do
+so raises the <i>SQLException</i> 4251A.</li>
+<li>You cannot create a role if a role with that name already exists. An attempt
+to do so raises the <i>SQLException</i> X0Y68.</li>
+<li>You cannot create a role name if there is a user by that name. An attempt to
+create a role name that conflicts with an existing user name raises the
+<i>SQLException</i> X0Y68.</li>
+<li>A role name cannot start with the prefix SYS (after case normalization). Use
+of the prefix SYS raises the <i>SQLException</i> 4293A.</li>
+<li>You cannot create a role with the name PUBLIC (after case normalization).
+PUBLIC is a reserved authorization identifier. An attempt to create a role with
+the name PUBLIC raises <i>SQLException</i> 4251B.</li>
+</ul>
+<p>The following errors can result from the DROP ROLE statement:</p>
+<ul>
+<li>You cannot drop a role if you are not the database owner. An attempt to do
+so raises the <i>SQLException</i> 4251A.</li>
+<li>You cannot drop a role that does not exist. An attempt to do so raises the
+<i>SQLException</i> 0P000.</li>
+</ul>
+<p>The following errors can result from the SET ROLE statement:</p>
+<ul>
+<li>You cannot set a role if you are not the database owner. An attempt to do so
+raises the <i>SQLException</i> 4251A.</li>
+<li>You cannot set a role that does not exist. An attempt to do so raises the
+<i>SQLException</i> 0P000.</li>
+<li>You cannot set a role when a transaction is in progress. An attempt to do so
+raises the <i>SQLException</i> 25001.</li>
+<li>You cannot use NONE or a malformed identifier as a string or
+<codeph>?</codeph> argument to SET ROLE. An attempt to do so raises the
+<i>SQLException</i> XCXA0.</li>
+</ul>
+<p>The following errors can result from the GRANT statement:</p>
+<ul>
+<li>You cannot grant a role if you are not the database owner. An attempt to do
+so raises the <i>SQLException</i> 4251A.</li>
+<li>You cannot grant a role that does not exist. An attempt to do so raises the
+<i>SQLException</i> 0P000.</li>
+<li>You cannot grant the role "PUBLIC". An attempt to do so raises the
+<i>SQLException</i> 4251B.</li>
+<li>You cannot grant a role if doing so would create a circularity by granting
+a container role to a contained role. An attempt to do so raises the
+<i>SQLException</i> 4251C.</li>
+</ul>
+<p>The following errors can result from the REVOKE statement:</p>
+<ul>
+<li>You cannot revoke a role if you are not the database owner. An attempt to do
+so raises the <i>SQLException</i> 4251A.</li>
+<li>You cannot revoke a role that does not exist. An attempt to do so raises the
+<i>SQLException</i> 0P000.</li>
+<li>You cannot revoke the role "PUBLIC". An attempt to do so raises the
+<i>SQLException</i> 4251B.</li>
+</ul>
+<p>For all statements, an attempt to specify an identifier argument more than
+128 characters long raises the <i>SQLException</i> 42622.</p>.
+</section>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/devguide/rdevcsecuresqlauthexceptions.dita
------------------------------------------------------------------------------
svn:eol-style = native
Modified: db/derby/docs/trunk/src/ref/crefsqlj35312.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/crefsqlj35312.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/crefsqlj35312.dita (original)
+++ db/derby/docs/trunk/src/ref/crefsqlj35312.dita Mon Jan 5 11:50:47 2009
@@ -21,7 +21,7 @@
<concept id="crefsqlj35312" xml:lang="en-us">
<title>SET statements</title>
<conbody>
-<p>Use the Set statements with schemas and to set the current isolation level.</p>
+<p>Use the SET statements to set the current role, schema, or isolation level.</p>
</conbody>
</concept>
Modified: db/derby/docs/trunk/src/ref/crefsqlj80721.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/crefsqlj80721.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/crefsqlj80721.dita (original)
+++ db/derby/docs/trunk/src/ref/crefsqlj80721.dita Mon Jan 5 11:50:47 2009
@@ -21,8 +21,8 @@
<concept id="crefsqlj80721" xml:lang="en-us">
<title>DROP statements</title>
<conbody>
-<p>Use Drop statements with functions, indexes, procedures, schemas, synonyms, tables,
-triggers, and views.</p>
+<p>Use DROP statements to remove functions, indexes, procedures, roles, schemas,
+synonyms, tables, triggers, and views.</p>
</conbody>
</concept>
Modified: db/derby/docs/trunk/src/ref/crefsqlj95081.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/crefsqlj95081.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/crefsqlj95081.dita (original)
+++ db/derby/docs/trunk/src/ref/crefsqlj95081.dita Mon Jan 5 11:50:47 2009
@@ -21,8 +21,8 @@
<concept id="crefsqlj95081" xml:lang="en-us">
<title>CREATE statements</title>
<conbody>
-<p>Use the Create statements with functions, indexes, procedures, schemas, synonyms,
-tables, triggers, and views.</p>
+<p>Use the CREATE statements to create functions, indexes, procedures, roles,
+schemas, synonyms, tables, triggers, and views.</p>
</conbody>
</concept>
Modified: db/derby/docs/trunk/src/ref/refderby.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/refderby.ditamap?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/refderby.ditamap (original)
+++ db/derby/docs/trunk/src/ref/refderby.ditamap Mon Jan 5 11:50:47 2009
@@ -69,6 +69,44 @@
<topicref href="rrefsqljrevoke.dita" navtitle="REVOKE statement "></topicref>
</relcell>
</relrow>
+<relrow>
+<relcell>
+<topicref href="rrefcreaterole.dita" navtitle="CREATE ROLE statement"></topicref>
+</relcell>
+<relcell>
+<topicref href="rrefsetrole.dita" navtitle="SET ROLE statement"></topicref>
+<topicref href="rrefdroprole.dita" navtitle="DROP ROLE statement"></topicref>
+<topicref href="rrefcurrentrole.dita" navtitle="CURRENT_ROLE function"></topicref>
+<topicref href="rrefsistabssysroles.dita" navtitle="SYSROLES system table"></topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
+<topicref href="rrefsetrole.dita" navtitle="SET ROLE statement"></topicref>
+</relcell>
+<relcell>
+<topicref href="rrefdroprole.dita" navtitle="DROP ROLE statement"></topicref>
+<topicref href="rrefcurrentrole.dita" navtitle="CURRENT_ROLE function"></topicref>
+<topicref href="rrefsistabssysroles.dita" navtitle="SYSROLES system table"></topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
+<topicref href="rrefdroprole.dita" navtitle="DROP ROLE statement"></topicref>
+</relcell>
+<relcell>
+<topicref href="rrefcurrentrole.dita" navtitle="CURRENT_ROLE function"></topicref>
+<topicref href="rrefsistabssysroles.dita" navtitle="SYSROLES system table"></topicref>
+</relcell>
+</relrow>
+<relrow>
+<relcell>
+<topicref href="rrefcurrentrole.dita" navtitle="CURRENT_ROLE function"></topicref>
+</relcell>
+<relcell>
+<topicref href="rrefsistabssysroles.dita" navtitle="SYSROLES system table"></topicref>
+</relcell>
+</relrow>
</reltable>
<topicref href="rrefcopyright.dita" navtitle="Copyright"></topicref>
<topicref href="rreflicense.dita" navtitle="License"></topicref>
@@ -103,6 +141,7 @@
<topicref href="rrefcursorname.dita" navtitle="cursor-Name"></topicref>
<topicref href="rreftriggername.dita" navtitle="TriggerName"></topicref>
<topicref href="rrefrauthid.dita" navtitle="AuthorizationIdentifier"></topicref>
+<topicref href="rrefrolename.dita" navtitle="RoleName"></topicref>
</topicref>
<topicref href="crefsqlj39374.dita" navtitle="Statements">
<topicref href="crefsqlj22771.dita" navtitle="Interaction with the dependency system">
@@ -115,6 +154,7 @@
<topicref href="rrefsqlj20937.dita" navtitle="CREATE INDEX statement"></topicref>
<topicref href="rrefcreateprocedurestatement.dita" navtitle="CREATE PROCEDURE statement">
</topicref>
+<topicref href="rrefcreaterole.dita" navtitle="CREATE ROLE statement"></topicref>
<topicref href="rrefsqlj31580.dita" navtitle="CREATE SCHEMA statement"></topicref>
<topicref href="rrefsqljcreatesynonym.dita" navtitle="CREATE SYNONYM statement">
</topicref>
@@ -139,6 +179,7 @@
<topicref href="rrefsqlj59893.dita" navtitle="DROP INDEX statement"></topicref>
<topicref href="rrefdropprocedurestatement.dita" navtitle="DROP PROCEDURE statement">
</topicref>
+<topicref href="rrefdroprole.dita" navtitle="DROP ROLE statement"></topicref>
<topicref href="rrefsqlj31648.dita" navtitle="DROP SCHEMA statement"></topicref>
<topicref href="rrefsqljdropsynonym.dita" navtitle="DROP SYNONYM statement">
</topicref>
@@ -160,6 +201,7 @@
<topicref collection-type="family" href="crefsqlj35312.dita" navtitle="SET statements">
<topicref href="rrefsqlj41180.dita" navtitle="SET CURRENT ISOLATION statement">
</topicref>
+<topicref href="rrefsetrole.dita" navtitle="SET ROLE statement"></topicref>
<topicref href="rrefsqlj32268.dita" navtitle="SET SCHEMA statement"></topicref>
</topicref>
<topicref href="rrefsqlj41360.dita" navtitle="SELECT statement"></topicref>
@@ -237,6 +279,7 @@
<topicref href="rrefsqlj34177.dita" navtitle="CURRENT_DATE function"></topicref>
<topicref href="rrefcurrentisolation.dita" navtitle="CURRENT ISOLATION function">
</topicref>
+<topicref href="rrefcurrentrole.dita" navtitle="CURRENT_ROLE function"></topicref>
<topicref href="rrefsqljcurrentschema.dita" navtitle="CURRENT SCHEMA function">
</topicref>
<topicref href="rrefsqlj1055824.dita" navtitle="CURRENT TIME function"></topicref>
@@ -423,6 +466,7 @@
<topicref href="rrefsistabs13420.dita" navtitle="SYSFOREIGNKEYS system table">
</topicref>
<topicref href="rrefsistabs33921.dita" navtitle="SYSKEYS system table"></topicref>
+<topicref href="rrefsistabssysroles.dita" navtitle="SYSROLES system table"></topicref>
<topicref href="rrefsistabssysroutineperms.dita" navtitle="SYSROUTINEPERMS system table">
</topicref>
<topicref href="rrefsistabs12085.dita" navtitle="SYSSCHEMAS system table">
Added: db/derby/docs/trunk/src/ref/rrefcreaterole.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefcreaterole.dita?rev=731664&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefcreaterole.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefcreaterole.dita Mon Jan 5 11:50:47 2009
@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<reference id="rrefcreaterole" xml:lang="en-us">
+<title>CREATE ROLE statement</title>
+<prolog><metadata>
+<keywords>
+<indexterm>CREATE ROLE statement</indexterm>
+<indexterm>SQL statements<indexterm>CREATE ROLE</indexterm></indexterm>
+<indexterm>roles<indexterm>creating</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section>
+<p>The CREATE ROLE statement allows you to create an SQL role.</p>
+<p>Only the
+<xref href="rrefattrib26867.dita#rrefattrib26867">database owner</xref> can
+create a role.</p>
+<p>For more information on roles, see "Using SQL roles" in the
+<ph conref="../conrefs.dita#pub/citdevelop"></ph>.</p>
+</section>
+<refsyn><title>Syntax</title>
+<codeblock>
+<b>CREATE ROLE <i><xref href="rrefrolename.dita#rrefrolename">roleName</xref></i>
+</b></codeblock>
+</refsyn>
+<section>
+<p>Before you issue a CREATE ROLE statement, verify that the
+<i><xref href="rrefpropersqlauth.dita#rrefpropersqlauth">derby.database.sqlAuthorization</xref></i>
+property is set to <codeph>TRUE</codeph>. The
+<i>derby.database.sqlAuthorization</i> property enables SQL authorization mode.
+</p>
+<p>You cannot create a role name if there is a user by that name. An attempt
+to create a role name that conflicts with an existing user name raises the
+<i>SQLException</i> X0Y68.</p>
+<p>If user names are not controlled by the database owner (or administrator),
+it may be a good idea to use a naming convention for roles to reduce the
+possibility of collision with user names.</p>
+<p><ph conref="../conrefs.dita#prod/productshortname"></ph> tries to avoid name
+collision between user names and role names, but this is not always possible,
+because <ph conref="../conrefs.dita#prod/productshortname"></ph> has a
+pluggable authorization architecture. For example, an externally defined user
+may exist who has never yet connected to the database, created any schema
+objects, or been granted any privileges. If
+<ph conref="../conrefs.dita#prod/productshortname"></ph> knows about a user
+name, it will forbid creating a role with that name. Correspondingly, a user
+who has the same name as a role will not be allowed to connect.
+<ph conref="../conrefs.dita#prod/productshortname"></ph> built-in users are
+checked for collision when a role is created.</p>
+<p>A role name cannot start with the prefix SYS (after case normalization). The
+purpose of this restriction is to reserve a name space for system-defined roles
+at a later point. Use of the prefix SYS raises the <i>SQLException</i> 4293A.
+</p>
+<p>You cannot create a role with the name <codeph>PUBLIC</codeph> (after case
+normalization). <codeph>PUBLIC</codeph> is a reserved authorization identifier.
+An attempt to create a role with the name <codeph>PUBLIC</codeph> raises
+<i>SQLException</i> 4251B.</p>
+</section>
+<example><title>Example of creating a role</title>
+<codeblock><b>CREATE ROLE purchases_reader;</b></codeblock>
+</example>
+<example><title>Examples of invalid role names</title>
+<codeblock><b>CREATE ROLE public; -- throws SQLException;
+CREATE ROLE "PUBLIC"; -- throws SQLException;
+CREATE ROLE sysrole; -- throws SQLException;</b></codeblock>
+</example>
+<example><title>Example of creating a role using a naming convention</title>
+<p>The following example uses the convention of giving every role name the
+suffix <codeph>_role</codeph>.</p>
+<codeblock><b>CREATE ROLE purchases_reader_role;</b></codeblock>
+</example>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/ref/rrefcreaterole.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/ref/rrefcurrentrole.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefcurrentrole.dita?rev=731664&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefcurrentrole.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefcurrentrole.dita Mon Jan 5 11:50:47 2009
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "../dtd/reference.dtd">
+<reference id="rrefcurrentrole" xml:lang="en-us">
+<title>CURRENT_ROLE function</title>
+<prolog><metadata>
+<keywords><indexterm>CURRENT_ROLE function</indexterm></keywords>
+</metadata></prolog>
+<refbody>
+<section>
+<p>CURRENT_ROLE returns the authorization identifier of the current
+role. If there is no current role, it returns NULL.</p>
+<p>This function returns a string of up to 258 characters. This is twice the
+length of an identifier (128*2) + 2, to allow for quoting.</p>
+</section>
+<refsyn><title>Syntax</title>
+<codeblock><b>CURRENT_ROLE</b></codeblock>
+</refsyn>
+<example><title>Example</title>
+<codeblock><b>VALUES CURRENT_ROLE</b></codeblock>
+</example>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/ref/rrefcurrentrole.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/ref/rrefdroprole.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefdroprole.dita?rev=731664&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefdroprole.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefdroprole.dita Mon Jan 5 11:50:47 2009
@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "../dtd/reference.dtd">
+<reference id="rrefdroprole" xml:lang="en-us">
+<title>DROP ROLE statement</title>
+<prolog><metadata>
+<keywords><indexterm>DROP ROLE statement</indexterm>
+<indexterm>SQL statements<indexterm>DROP ROLE</indexterm></indexterm>
+<indexterm>roles<indexterm>dropping</indexterm></indexterm>
+</keywords></metadata>
+</prolog>
+<refbody>
+<section>
+<p>The DROP ROLE statement allows you to drop an SQL role.</p>
+<p>Only the
+<xref href="rrefattrib26867.dita#rrefattrib26867">database owner</xref> can drop
+a role.</p>
+<p>For more information on roles, see "Using SQL roles" in the
+<ph conref="../conrefs.dita#pub/citdevelop"></ph>.</p>
+</section>
+<refsyn><title>Syntax</title>
+<codeblock>
+<b>DROP ROLE <i><xref href="rrefrolename.dita#rrefrolename">roleName</xref></i></b>
+</codeblock>
+</refsyn>
+<section>
+<p>Dropping a role has the effect of removing the role from the database
+dictionary. This means that no session user can henceforth set that role (see
+<xref href="rrefsetrole.dita#rrefsetrole"></xref>), and any existing sessions
+that have that role as the current role (see
+<xref href="rrefcurrentrole.dita#rrefcurrentrole"></xref>) will now have a NULL
+CURRENT_ROLE. Dropping a role also has the effect of revoking that role from any
+user and role it has been granted to. See
+<xref href="rrefsqljrevoke.dita#rrefsqljrevoke"></xref> for information on how
+revoking a role may impact any dependent objects.</p>
+</section>
+<example><title>Example</title>
+<codeblock><b>DROP ROLE reader;</b></codeblock>
+</example>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/ref/rrefdroprole.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/ref/rrefrolename.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefrolename.dita?rev=731664&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefrolename.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefrolename.dita Mon Jan 5 11:50:47 2009
@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "../dtd/reference.dtd">
+<reference id="rrefrolename" xml:lang="en-us">
+<title>RoleName</title>
+<refbody>
+<section>
+<p>A <i>RoleName</i> refers to an SQL role. A role in a database is uniquely
+identified by its role name.</p>
+</section>
+<refsyn><title>Syntax</title>
+<codeblock>
+<b><i><xref href="crefsqlj34834.dita#crefsqlj34834">SQL92Identifier</xref></i>
+</b></codeblock>
+</refsyn>
+<section>
+<p>In terms of SQL, a role name is also technically an
+<i><xref href="rrefrauthid.dita#rrefrauthid">AuthorizationIdentifier</xref></i>,
+but that term is often used for user names in
+<ph conref="../conrefs.dita#prod/productshortname"></ph> for historical reasons.
+</p>
+</section>
+<example><title>Example</title>
+<codeblock><b>DROP ROLE reader</b></codeblock>
+</example>
+</refbody>
+</reference>
+
Propchange: db/derby/docs/trunk/src/ref/rrefrolename.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/ref/rrefsetrole.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsetrole.dita?rev=731664&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsetrole.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefsetrole.dita Mon Jan 5 11:50:47 2009
@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "../dtd/reference.dtd">
+<reference id="rrefsetrole" xml:lang="en-us">
+<title>SET ROLE statement</title>
+<prolog><metadata>
+<keywords><indexterm>SET ROLE statement</indexterm>
+<indexterm>SQL statements<indexterm>SET ROLE</indexterm></indexterm>
+<indexterm>roles<indexterm>setting</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<refbody>
+<section>
+<p>The SET ROLE statement allows you to set the current role for the
+current SQL context of a session.</p>
+<p>You can set a role only if the current user has been granted the role, or
+if the role has been granted to PUBLIC.</p>
+<p>For more information on roles, see "Using SQL roles" in the
+<ph conref="../conrefs.dita#pub/citdevelop"></ph>.</p>
+</section>
+<refsyn><title>Syntax</title>
+<codeblock>
+<b>SET ROLE { <i><xref href="rrefrolename.dita#rrefrolename">roleName</xref></i> | 'string-constant' | ? | NONE }
+</b></codeblock>
+</refsyn>
+<section>
+<p>If you specify a <i>roleName</i> of NONE, the effect is to unset the current
+role.</p>
+<p>If you specify the role as a string constant or as a dynamic parameter
+specification (<codeph>?</codeph>), any leading and trailing blanks are trimmed
+from the string before attempting to use the remaining (sub)string as a
+<i>roleName</i>. The dynamic parameter specification can be used in prepared
+statements, so the SET ROLE statement can be prepared once and then executed
+with different role values. You cannot specify NONE as a dynamic parameter.</p>
+<p>Setting a role identifies a set of privileges that is a union of the
+following:</p>
+<ul>
+<li>The privileges granted to that role</li>
+<li>The union of privileges of roles contained in that role (for a definition of
+role containment, see "Syntax for roles" in <xref
+href="rrefsqljgrant.dita#rrefsqljgrant/grantrolesyn">GRANT statement</xref>)
+</li>
+</ul>
+<p>In a session, the <i>current privileges</i> define what the session is
+allowed to access. The <i>current privileges</i> are the union of the
+following:</p>
+<ul>
+<li>The privileges granted to the current user</li>
+<li>The privileges granted to PUBLIC</li>
+<li>The privileges identified by the current role, if set</li>
+</ul>
+<p>The SET ROLE statement is not transactional; a rollback does not undo the
+effect of setting a role. If a transaction is in progress, an attempt to set a
+role results in an error.</p>
+</section>
+<example><title>Examples</title>
+<codeblock><b>SET ROLE reader;</b></codeblock>
+<codeblock><b> // These examples show the use of SET ROLE in JDBC statements.
+ // The case normal form is visible in the SYS.SYSROLES system table.
+ stmt.execute("SET ROLE admin"); -- case normal form: ADMIN
+ stmt.execute("SET ROLE \"admin\""); -- case normal form: admin
+ stmt.execute("SET ROLE none"); -- special case
+
+ PreparedStatement ps = conn.prepareStatement("SET ROLE ?");
+ ps.setString(1, " admin "); -- on execute: case normal form: ADMIN
+ ps.setString(1, "\"admin\""); -- on execute: case normal form: admin
+ ps.setString(1, "none"); -- on execute: syntax error
+ ps.setString(1, "\"none\""); -- on execute: case normal form: none
+</b></codeblock>
+</example>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/ref/rrefsetrole.dita
------------------------------------------------------------------------------
svn:eol-style = native
Modified: db/derby/docs/trunk/src/ref/rrefsistabssyscolperms.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsistabssyscolperms.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsistabssyscolperms.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsistabssyscolperms.dita Mon Jan 5 11:50:47 2009
@@ -65,7 +65,7 @@
<entry colname="2">VARCHAR</entry>
<entry colname="3">30</entry>
<entry colname="4">False</entry>
-<entry colname="5">The authorization ID of the user to whom the privilege
+<entry colname="5">The authorization ID of the user or role to which the privilege
was granted. </entry>
</row>
<row>
Added: db/derby/docs/trunk/src/ref/rrefsistabssysroles.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsistabssysroles.dita?rev=731664&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsistabssysroles.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefsistabssysroles.dita Mon Jan 5 11:50:47 2009
@@ -0,0 +1,114 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "reference.dtd">
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+<reference id="rrefsistabssysroles" xml:lang="en-us">
+<title>SYSROLES system table</title>
+<shortdesc>The SYSROLES table stores the roles in the database.</shortdesc>
+<prolog><metadata>
+<keywords><indexterm>system tables<indexterm>SYSROLES</indexterm></indexterm>
+<indexterm>SQL roles<indexterm>SYSROLES system table</indexterm></indexterm>
+<indexterm>SYSROLES system table</indexterm></keywords>
+</metadata></prolog>
+<refbody>
+<section><p>A row in the SYSROLES table represents one of the following:</p>
+<ul>
+<li>A role definition (the result of a <xref
+href="rrefcreaterole.dita#rrefcreaterole">CREATE ROLE statement</xref>)</li>
+<li>A role grant</li>
+</ul>
+<p>The keys for the SYSROLES table are: <ul>
+<li>Primary key (GRANTEE, ROLEID, GRANTOR)</li>
+<li>Unique key (UUID)</li>
+</ul> </p></section>
+<table frame="all" pgwide="1">
+<tgroup cols="5" colsep="1" rowsep="1"><colspec colname="1" colnum="1" colwidth="27*"/>
+<colspec colname="2" colnum="2" colwidth="10*"/><colspec colname="3" colnum="3"
+colwidth="11*"/><colspec colname="4" colnum="4" colwidth="14*"/><colspec colname="5"
+colnum="5" colwidth="38*"/>
+<thead>
+<row>
+<entry align="left" colname="1" valign="bottom">Column Name</entry>
+<entry align="left" colname="2" valign="bottom">Type</entry>
+<entry align="left" colname="3" valign="bottom">Length</entry>
+<entry align="left" colname="4" valign="bottom">Nullability</entry>
+<entry align="left" colname="5" valign="bottom">Contents</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry colname="1">UUID</entry>
+<entry colname="2">CHAR</entry>
+<entry colname="3">36</entry>
+<entry colname="4">False</entry>
+<entry colname="5">A unique identifier for this role.</entry>
+</row>
+<row>
+<entry colname="1">ROLEID</entry>
+<entry colname="2">VARCHAR</entry>
+<entry colname="3">128</entry>
+<entry colname="4">False</entry>
+<entry colname="5">The role name, after conversion to case normal form.</entry>
+</row>
+<row>
+<entry colname="1">GRANTEE</entry>
+<entry colname="2">VARCHAR</entry>
+<entry colname="3">128</entry>
+<entry colname="4">False</entry>
+<entry colname="5">If the row represents a role grant, this is the authorization
+identifier of a user or role to which this role is granted. If the row
+represents a role definition, this is the database owner's user name.</entry>
+</row>
+<row>
+<entry colname="1">GRANTOR</entry>
+<entry colname="2">VARCHAR</entry>
+<entry colname="3">128</entry>
+<entry colname="4">False</entry>
+<entry colname="5">This is the authorization identifier of the user that granted
+this role. If the row represents a role definition, this is the authorization
+identifier _SYSTEM. If the row represents a role grant, this is the database
+owner's user name (since only the database owner can create and grant roles).
+</entry>
+</row>
+<row>
+<entry colname="1">WITHADMINOPTION</entry>
+<entry colname="2">CHAR</entry>
+<entry colname="3">1</entry>
+<entry colname="4">False</entry>
+<entry colname="5">A role definition is modelled as a grant from _SYSTEM to the
+database owner, so if the row represents a role definition, the value is always
+'Y'. This means that the creator (the database owner) is always allowed to grant
+the newly created role. Currently roles cannot be granted WITH ADMIN OPTION, so
+if the row represents a role grant, the value is always 'N'.</entry>
+</row>
+<row>
+<entry colname="1">ISDEF</entry>
+<entry colname="2">CHAR</entry>
+<entry colname="3">1</entry>
+<entry colname="4">False</entry>
+<entry colname="5">If the row represents a role definition, this value is
+'Y'. If the row represents a role grant, the value is 'N'.</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+</refbody>
+</reference>
Propchange: db/derby/docs/trunk/src/ref/rrefsistabssysroles.dita
------------------------------------------------------------------------------
svn:eol-style = native
Modified: db/derby/docs/trunk/src/ref/rrefsistabssysroutineperms.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsistabssysroutineperms.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsistabssysroutineperms.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsistabssysroutineperms.dita Mon Jan 5 11:50:47 2009
@@ -59,7 +59,7 @@
<entry colname="2">VARCHAR</entry>
<entry colname="3">30</entry>
<entry colname="4">false</entry>
-<entry colname="5">The authorization ID of the user to whom the privilege
+<entry colname="5">The authorization ID of the user or role to which the privilege
is granted.</entry>
</row>
<row>
Modified: db/derby/docs/trunk/src/ref/rrefsistabssystableperms.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsistabssystableperms.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsistabssystableperms.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsistabssystableperms.dita Mon Jan 5 11:50:47 2009
@@ -65,7 +65,7 @@
<entry colname="2">VARCHAR</entry>
<entry colname="3">30</entry>
<entry colname="4">False</entry>
-<entry colname="5">The authorization ID of the user to whom the privilege
+<entry colname="5">The authorization ID of the user or role to which the privilege
is granted.</entry>
</row>
<row>
Modified: db/derby/docs/trunk/src/ref/rrefsqlj30540.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqlj30540.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqlj30540.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqlj30540.dita Mon Jan 5 11:50:47 2009
@@ -33,11 +33,11 @@
<section id="sqlj64478"><title>Column default</title><p>For the definition
of a default value, a <varname>DefaultConstantExpression</varname> is an
expression that does not refer to any table. It can include constants,
-date-time special registers, current schemas, users, and null: </p>
+date-time special registers, current schemas, users, roles, and null: </p>
<codeblock><b><varname>DefaultConstantExpression</varname>:
NULL
| CURRENT { SCHEMA | SQLID }
- | USER | CURRENT_USER | SESSION_USER
+ | USER | CURRENT_USER | SESSION_USER | CURRENT_ROLE
| DATE
| TIME
| TIMESTAMP
@@ -53,7 +53,7 @@
<varname>DefaultConstantExpression</varname> has the following additional type
restrictions:</p>
<ul>
-<li>If you specify USER, CURRENT_USER or SESSION_USER, the column must be a
+<li>If you specify USER, CURRENT_USER, SESSION_USER, or CURRENT_ROLE, the column must be a
character column whose length is at least 8.</li>
<li>If you specify CURRENT SCHEMA or CURRENT SQLID, the column must be a
character column whose length is at least 128.</li>
Modified: db/derby/docs/trunk/src/ref/rrefsqlj31580.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqlj31580.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqlj31580.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqlj31580.dita Mon Jan 5 11:50:47 2009
@@ -41,8 +41,13 @@
specify
<codeblock>AUTHORIZATION <i>user-name</i></codeblock>
with a user name other than the current user name. See
-<ph conref="../conrefs.dita#pub/cittuning"></ph> for information about the
+"<xref href="rrefpropersqlauth.dita#rrefpropersqlauth">derby.database.sqlAuthorization</xref>" for information about the
<codeph>derby.database.sqlAuthorization</codeph> property.</p>
+<note>Although the SQL standard allows you to specify any
+<i><xref href="rrefrauthid.dita#rrefrauthid">AuthorizationIdentifier</xref></i>
+as an AUTHORIZATION argument,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> allows you to specify
+only a user, not a role.</note>
</refsyn>
<example><title>CREATE SCHEMA examples</title><p>To create a schema for airline-related
tables and give the authorization ID <codeph>anita</codeph> access to all
Modified: db/derby/docs/trunk/src/ref/rrefsqljgrant.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqljgrant.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqljgrant.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqljgrant.dita Mon Jan 5 11:50:47 2009
@@ -22,8 +22,9 @@
-->
<reference id="rrefsqljgrant" xml:lang="en-us">
<title>GRANT statement </title>
-<shortdesc>Use the GRANT statement to give permissions to a specific user
-or all users to perform actions on database objects.</shortdesc>
+<shortdesc>Use the GRANT statement to give permissions to a specific user or
+role, or to all users, to perform actions on database objects. You can also use
+the GRANT statement to grant a role to a user or to another role.</shortdesc>
<prolog><metadata>
<keywords><indexterm>GRANT statement</indexterm><indexterm>SQL statements<indexterm>GRANT</indexterm></indexterm>
</keywords>
@@ -45,7 +46,10 @@
objects that you are authorized to grant. See the CREATE statement for the
database object that you want to grant privileges on for more information.</p><p>The
syntax that you use for the GRANT statement depends on whether you are granting
-privileges to a table or to a routine.</p></section>
+privileges to a table or to a routine, or granting a role.</p>
+<p>For more information on using the GRANT statement, see "Using SQL standard
+authorization" in the <ph conref="../conrefs.dita#pub/citdevelop"></ph>.</p>
+</section>
<section><title>Syntax for tables</title><codeblock><b>GRANT <i><xref href="rrefsqljgrant.dita#rrefsqljgrant/grantprivtype">privilege-type</xref></i
> ON [TABLE] { <i><xref href="rreftablename.dita#rreftablename"></xref></i> | <i><xref
href="rrefviewname.dita#rrefviewname"></xref></i> } TO <i><xref href="rrefsqljgrant.dita#rrefsqljgrant/grantgrantees">grantees</xref></i></b></codeblock
@@ -53,6 +57,19 @@
<section><title>Syntax for routines</title><codeblock><b>GRANT EXECUTE ON { FUNCTION | PROCEDURE } <i><xref
href="rrefsqljgrant.dita#rrefsqljgrant/grantroutinename">routine-designator</xref></i> TO <i><xref
href="rrefsqljgrant.dita#rrefsqljgrant/grantgrantees">grantees</xref></i></b></codeblock></section>
+<section id="grantrolesyn"><title>Syntax for roles</title>
+<codeblock><b>GRANT <i><xref href="rrefrolename.dita#rrefrolename">roleName</xref></i> [ {, <i><xref
+href="rrefrolename.dita#rrefrolename">roleName</xref></i> }* ] TO <i><xref
+href="rrefsqljgrant.dita#rrefsqljgrant/grantgrantees">grantees</xref></i></b></codeblock>
+<p>Before you can grant a role to a user or to another role, you must create the
+role using the <xref href="rrefcreaterole.dita#rrefcreaterole">CREATE ROLE
+statement</xref>. Only the
+<xref href="rrefattrib26867.dita#rrefattrib26867">database owner</xref> can
+grant a role.</p>
+<p>A role A <i>contains</i> another role B if role B is granted to role A, or is
+contained in a role granted to role A. In this case, the privileges identified
+by role B are inherited by role A.</p>
+</section>
<section id="grantprivtype"><title>privilege-types</title><codeblock><b> ALL PRIVILEGES |
privilege-list
</b></codeblock></section>
@@ -68,7 +85,7 @@
<section id="grantcollist"><title>column list</title><codeblock><b> ( column-identifier {, column-identifier}* )
</b></codeblock></section>
<section><p>Use the ALL PRIVILEGES privilege type to grant all of the permissions
-to the user for the specified table. You can also grant one or more table
+to the user or role for the specified table. You can also grant one or more table
privileges by specifying a privilege-list.</p><p>Use the DELETE privilege
type to grant permission to delete rows from the specified table.</p><p>Use
the INSERT privilege type to grant permission to insert rows into the specified
@@ -86,25 +103,39 @@
only to the specified columns. To update a row using a statement that includes
a WHERE clause, you must have SELECT permission on the columns in the row
that you want to update. </p></section>
-<section id="grantgrantees"><title>grantees</title><codeblock><b>{ <i>authorization ID</i> | PUBLIC } [,{ <i>authorization ID</i> | PUBLIC } ] *</b
-></codeblock><p>You can grant privileges for specific users or for all users.
+<section id="grantgrantees"><title>grantees</title>
+<codeblock><b>{ <i><xref href="rrefrauthid.dita#rrefrauthid">AuthorizationIdentifier</xref></i> | <i><xref href="rrefrolename.dita#rrefrolename">roleName</xref></i> | PUBLIC }
+[, { <i><xref href="rrefrauthid.dita#rrefrauthid">AuthorizationIdentifier</xref></i> | <i><xref href="rrefrolename.dita#rrefrolename">roleName</xref></i> | PUBLIC } ] *</b></codeblock>
+<p>You can grant privileges or roles to specific users or roles or to all users.
Use the keyword PUBLIC to specify all users. When PUBLIC is specified, the
-privileges affect all current and future users. The privileges granted to
-PUBLIC and to individual users are independent privileges. For example, a
-SELECT privilege on table <codeph>t</codeph> is granted to both PUBLIC and
-to the authorization ID <codeph>harry</codeph>. The SELECT privilege is later
-revoked from the authorization ID <codeph>harry</codeph>, but Harry can access
-the table <codeph>t</codeph> through the PUBLIC privilege.</p></section>
+privileges or roles affect all current and future users. The privileges granted
+to PUBLIC and to individual users or roles are independent privileges. For
+example, a SELECT privilege on table <codeph>t</codeph> is granted to both
+PUBLIC and to the authorization ID <codeph>harry</codeph>. The SELECT privilege
+is later revoked from the authorization ID <codeph>harry</codeph>, but Harry can
+access the table <codeph>t</codeph> through the PUBLIC privilege.</p>
+<p>Either the object owner or the database owner can grant privileges to a user
+or to a role. Only the database owner can grant a role to a user or to another
+role.</p></section>
<section id="grantroutinename"><title>routine-designator</title><codeblock><b>{
<i>function-name</i> | <i>procedure-name</i>
}</b></codeblock></section>
<example id="grantexamples"><title>Examples</title><p>To grant the SELECT
-privilege on table t to the authorization IDs <codeph>maria</codeph> and <codeph>harry</codeph>,
+privilege on table <codeph>t</codeph> to the authorization IDs <codeph>maria</codeph> and <codeph>harry</codeph>,
use the following syntax:<codeblock><b>GRANT SELECT ON TABLE t TO maria,harry</b> </codeblock></p><p>To
-grant the UPDATE and TRIGGER privileges on table t to the authorization IDs <codeph>anita</codeph> and <codeph>zhi</codeph>,
+grant the UPDATE and TRIGGER privileges on table <codeph>t</codeph> to the authorization IDs <codeph>anita</codeph> and <codeph>zhi</codeph>,
use the following syntax:<codeblock><b>GRANT UPDATE, TRIGGER ON TABLE t TO anita,zhi</b> </codeblock></p><p>To
-grant the SELECT privilege on table s.v to all users, use the following syntax:<codeblock><b>GRANT SELECT ON TABLE s.v to PUBLIC</b></codeblock></p
-><p>To grant the EXECUTE privilege on procedure p to the authorization ID <codeph>george</codeph>,
-use the following syntax:</p><codeblock><b>GRANT EXECUTE ON PROCEDURE p TO george</b> </codeblock></example>
+grant the SELECT privilege on table <codeph>s.v</codeph> to all users, use the following syntax:<codeblock><b>GRANT SELECT ON TABLE s.v to PUBLIC</b></codeblock></p
+><p>To grant the EXECUTE privilege on procedure <codeph>p</codeph> to the authorization ID <codeph>george</codeph>,
+use the following syntax:</p><codeblock><b>GRANT EXECUTE ON PROCEDURE p TO george</b> </codeblock>
+<p>To grant the role <codeph>purchases_reader_role</codeph> to the authorization
+IDs <codeph>george</codeph> and <codeph>maria</codeph>, use the following
+syntax:</p>
+<codeblock><b>GRANT purchases_reader_role TO george,maria</b></codeblock>
+<p>To grant the SELECT privilege on table <codeph>t</codeph> to the role
+<codeph>purchases_reader_role</codeph>, use the following syntax:</p>
+<codeblock><b>GRANT SELECT ON TABLE t TO purchases_reader_role</b></codeblock>
+</example>
+
</refbody>
</reference>
Modified: db/derby/docs/trunk/src/ref/rrefsqljrevoke.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqljrevoke.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqljrevoke.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqljrevoke.dita Mon Jan 5 11:50:47 2009
@@ -20,7 +20,9 @@
<reference id="rrefsqljrevoke" xml:lang="en-us">
<title>REVOKE statement </title>
<shortdesc>Use the REVOKE statement to remove permissions from a specific
-user or from all users to perform actions on database objects.</shortdesc>
+user or role, or from all users, to perform actions on database objects. You can
+also use the REVOKE statement to revoke a role from a user or from another
+role.</shortdesc>
<prolog><metadata>
<keywords><indexterm>REVOKE statement<indexterm>syntax</indexterm></indexterm>
<indexterm>SQL statements<indexterm>REVOKE</indexterm></indexterm><indexterm>REVOKE
@@ -37,13 +39,19 @@
<li>Create a trigger on a table.</li>
<li>Update data in a table or in a subset of columns in a table.</li>
<li>Run a specified routine (function or procedure).</li>
-</ul></p><p>Before you issue a REVOKE statement, check that the
-<codeph><xref href="rrefpropersqlauth.dita#rrefpropersqlauth">derby.database.sqlAuthorization</xref></codeph> property
-is set to <codeph>true</codeph>. The <codeph>derby.database.sqlAuthorization</codeph> property
-enables the SQL Authorization mode.</p><p>You can revoke privileges from an
+</ul></p><p>The
+<codeph><xref href="rrefpropersqlauth.dita#rrefpropersqlauth">derby.database.sqlAuthorization</xref></codeph>
+property must be set to <codeph>true</codeph> before you can use the GRANT
+statement or the REVOKE statement. The
+<codeph>derby.database.sqlAuthorization</codeph> property
+enables SQL Authorization mode.</p><p>You can revoke privileges for an
object if you are the owner of the object or the <xref href="rrefattrib26867.dita#rrefattrib26867">database
owner</xref>.</p><p>The syntax that you use for the REVOKE statement depends
-on whether you are revoking privileges to a table or to a routine.</p></section>
+on whether you are revoking privileges to a table or to a routine, or whether
+you are revoking a role.</p>
+<p>For more information on using the REVOKE statement, see "Using SQL standard
+authorization" in the <ph conref="../conrefs.dita#pub/citdevelop"></ph>.</p>
+</section>
<section><title>Syntax for tables</title><codeblock><b>REVOKE <i><xref href="rrefsqljrevoke.dita#rrefsqljrevoke/revokeprivtype">privilege-type</xref
></i> ON [ TABLE ] { <i><xref href="rreftablename.dita#rreftablename"></xref></i> | <i><xref
href="rrefviewname.dita#rrefviewname"></xref></i> } FROM <i><xref href="rrefsqljrevoke.dita#rrefsqljrevoke/revokegrantees">grantees</xref></i></b
@@ -56,6 +64,13 @@
clause specifies that the EXECUTE privilege cannot be revoked if the specified
routine is used in a view, trigger, or constraint, and the privilege is being
revoked from the owner of the view, trigger, or constraint.</p></section>
+<section><title>Syntax for roles</title>
+<codeblock><b>REVOKE <i><xref href="rrefrolename.dita#rrefrolename">roleName</xref></i> [ {, <i><xref
+href="rrefrolename.dita#rrefrolename">roleName</xref></i> }* ] FROM <i><xref
+href="rrefsqljrevoke.dita#rrefsqljrevoke/revokegrantees">grantees</xref></i></b></codeblock>
+<p>Only the <xref href="rrefattrib26867.dita#rrefattrib26867">database
+owner</xref> can revoke a role.</p>
+</section>
<section id="revokeprivtype"><title>privilege-types</title><codeblock><b> ALL PRIVILEGES |
privilege-list </b></codeblock></section>
<section id="revokeprivlist"><title>privilege-list</title><codeblock><b> table-privilege {, table-privilege }* </b></codeblock></section>
@@ -67,7 +82,7 @@
UPDATE [<i>column list</i>] </b></codeblock></section>
<section id="revokecollist"><title>column list</title><codeblock><b> ( column-identifier {, column-identifier}* ) </b></codeblock></section>
<section><p>Use the ALL PRIVILEGES privilege type to revoke all of the permissions
-from the user for the specified table. You can also revoke one or more table
+from the user or role for the specified table. You can also revoke one or more table
privileges by specifying a privilege-list.</p><p>Use the DELETE privilege
type to revoke permission to delete rows from the specified table.</p><p>Use
the INSERT privilege type to revoke permission to insert rows into the specified
@@ -83,15 +98,19 @@
the UPDATE privilege type to revoke permission to use the UPDATE statement
on the specified table. If a column list is specified, the permission is revoked
only on the specified columns.</p></section>
-<section id="revokegrantees"><title>grantees</title><codeblock><b> { <i>authorization ID</i> | PUBLIC } [,{ <i>authorization ID</i> | PUBLIC } ] *</b
-></codeblock><p>You can revoke the privileges from specific users or from
+<section id="revokegrantees"><title>grantees</title>
+<codeblock><b>{ <i><xref href="rrefrauthid.dita#rrefrauthid">AuthorizationIdentifier</xref></i> | <i><xref href="rrefrolename.dita#rrefrolename">roleName</xref></i> | PUBLIC }
+[,{ <i><xref href="rrefrauthid.dita#rrefrauthid">AuthorizationIdentifier</xref></i> | <i><xref href="rrefrolename.dita#rrefrolename">roleName</xref></i> | PUBLIC } ] *</b
+></codeblock><p>You can revoke the privileges from specific users or roles or from
all users. Use the keyword PUBLIC to specify all users. The privileges revoked
-from PUBLIC and from individual users are independent privileges. For example,
+from PUBLIC and from individual users or roles are independent privileges. For example,
a SELECT privilege on table <codeph>t</codeph> is granted to both PUBLIC and
to the authorization ID <codeph>harry</codeph>. The SELECT privilege is later
revoked from the authorization ID <codeph>harry</codeph>, but the authorization
ID <codeph>harry</codeph> can access the table <codeph>t</codeph> through
-the PUBLIC privilege.</p><note type="restriction">You cannot revoke the privileges
+the PUBLIC privilege.</p>
+<p>You can revoke a role from a role, from a user, or from PUBLIC.</p>
+<note type="restriction">You cannot revoke the privileges
of the owner of an object.</note></section>
<section id="revokeroutinename"><title>routine-designator</title><codeblock><b> {
<i>qualified-name</i> [ signature ]
@@ -101,7 +120,7 @@
the object is automatically dropped. <ph conref="../conrefs.dita#prod/productshortname"></ph> does
not try to determine if you have other privileges that can replace the privileges
that are being revoked. For more information, see "SQL standard authorization"
-in the <ph conref="../conrefs.dita#pub/citdevelop">Derby Developer's Guide</ph>.</p></section>
+in the <ph conref="../conrefs.dita#pub/citdevelop"></ph>.</p></section>
<section><title>Limitations</title><p>The following limitations apply to the
REVOKE statement:</p><dl><dlentry>
<dt>Table-level privileges</dt>
@@ -154,7 +173,20 @@
a revoke invalidation message to the view <codeph>user2.v1</codeph> and the
view is dropped even though the view is not dependent on the column <codeph>c12</codeph> for
GRANTEE(<codeph>user2</codeph>), TABLEID(<codeph>user1.t1</codeph>), TYPE(S).</p></dd>
-</dlentry></dl></section>
+</dlentry>
+<dlentry>
+<dt>Roles</dt>
+<dd><ph conref="../conrefs.dita#prod/productshortname"></ph> tracks any
+dependencies on the definer's current role for views, constraints, and triggers.
+If privileges were obtainable only via the current role when the object in
+question was defined, that object depends on the current role. The object will
+be dropped if the role is revoked from the defining user or from PUBLIC, as the
+case may be. Also, if a contained role of the current role in such cases is
+revoked, dependent objects will be dropped. Note that dropping may be too
+pessimistic. This is because
+<ph conref="../conrefs.dita#prod/productshortname"></ph> does not currently make
+an attempt to re-check if the necessary privileges are still available in such
+cases.</dd></dlentry></dl></section>
<example> <title>Revoke examples</title><p>To revoke the SELECT privilege
on table <codeph>t</codeph> from the authorization IDs <codeph>maria</codeph> and <codeph>harry</codeph>,
use the following syntax:<codeblock><b>REVOKE SELECT ON TABLE t FROM maria,harry</b> </codeblock></p><p>To
@@ -166,7 +198,14 @@
revoke the UPDATE privilege on columns <codeph>c1</codeph> and <codeph>c2</codeph> of
table <codeph>s.v</codeph> from all users, use the following syntax:<codeblock><b>REVOKE UPDATE (c1,c2) ON TABLE s.v FROM PUBLIC</b></codeblock></p
><p>To revoke the EXECUTE privilege on procedure <codeph>p</codeph> from the
-authorization ID <codeph>george</codeph>, use the following syntax:</p><codeblock><b>REVOKE EXECUTE ON PROCEDURE p FROM george RESTRICT</b> </codeblock
-></example>
+authorization ID <codeph>george</codeph>, use the following syntax:</p><codeblock><b>REVOKE EXECUTE ON PROCEDURE p FROM george RESTRICT</b> </codeblock>
+<p>To revoke the role <codeph>purchases_reader_role</codeph> from the
+authorization IDs <codeph>george</codeph> and <codeph>maria</codeph>, use the
+following syntax:</p>
+<codeblock><b>REVOKE purchases_reader_role FROM george,maria</b></codeblock>
+<p>To revoke the SELECT privilege on table <codeph>t</codeph> from the role
+<codeph>purchases_reader_role</codeph>, use the following syntax:</p>
+<codeblock><b>REVOKE SELECT ON TABLE t FROM purchases_reader_role</b></codeblock>
+</example>
</refbody>
</reference>
Modified: db/derby/docs/trunk/src/ref/rrefsyscsdiagtables.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsyscsdiagtables.dita?rev=731664&r1=731663&r2=731664&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsyscsdiagtables.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsyscsdiagtables.dita Mon Jan 5 11:50:47 2009
@@ -35,7 +35,11 @@
diagnostic table</indexterm><indexterm>diagnostic table functions<indexterm>SYSCS_DIAG.STATEMENT_DURATION</indexterm></indexterm>
<indexterm>SYSCS_DIAG.STATEMENT_DURATION diagnostic table functions</indexterm>
<indexterm>diagnostic tables<indexterm>SYSCS_DIAG.TRANSACTION_TABLE</indexterm></indexterm>
-<indexterm>SYSCS_DIAG.TRANSACTION_TABLE diagnostic table</indexterm></keywords>
+<indexterm>SYSCS_DIAG.TRANSACTION_TABLE diagnostic table</indexterm>
+<indexterm>diagnostic tables<indexterm>SYSCS_DIAG.TRANSACTION_TABLE</indexterm></indexterm>
+<indexterm>SYSCS_DIAG.CONTAINED_ROLES diagnostic table function</indexterm>
+<indexterm>diagnostic table functions<indexterm>SYSCS_DIAG.CONTAINED_ROLES</indexterm></indexterm>
+</keywords>
</metadata></prolog>
<refbody>
<section> <p>There are two types of diagnostic table expressions in <ph conref="../conrefs.dita#prod/productshortname"></ph>:<dl>
@@ -63,6 +67,10 @@
</thead>
<tbody>
<row>
+<entry colname="col1">SYSCS_DIAG.CONTAINED_ROLES</entry>
+<entry colname="col2">Table function</entry>
+</row>
+<row>
<entry colname="col1">SYSCS_DIAG.ERROR_LOG_READER</entry>
<entry colname="col2">Table function</entry>
</row>
@@ -92,9 +100,18 @@
</row>
</tbody>
</tgroup>
-</table><p><note type="restriction">If you reference a diagnostic table in
+</table><note type="restriction">If you reference a diagnostic table in
a DDL statement or a compression procedure, <ph conref="../conrefs.dita#prod/productshortname"></ph> returns
-an exception. </note></p></section>
+an exception.</note></section>
+<section><title>SYSCS_DIAG.CONTAINED_ROLES diagnostic table function</title>
+<p>The SYSCS_DIAG.CONTAINED_ROLES diagnostic table function returns all the
+roles contained within the specified role. For a definition of role containment,
+see "Syntax for roles" in
+<xref href="rrefsqljgrant.dita#rrefsqljgrant/grantrolesyn">GRANT
+statement</xref>.</p>
+<p>For example:</p>
+<codeblock>SELECT * FROM TABLE (SYSCS_DIAG.CONTAINED_ROLES(reader))</codeblock>
+</section>
<section><title>SYSCS_DIAG.ERROR_LOG_READER diagnostic table function</title><p>The
SYSCS_DIAG.ERROR_LOG_READER diagnostic table function contains all the useful
SQL statements that are in the <filepath>derby.log</filepath> file or a log