Package org.apache.wiki.auth.authorize

# Class JDBCGroupDatabase

java.lang.Object
org.apache.wiki.auth.authorize.JDBCGroupDatabase

All Implemented Interfaces:
  `GroupDatabase`

public class JDBCGroupDatabase extends Object implements GroupDatabase

Implementation of GroupDatabase that persists `Group` objects to a JDBC DataSource, as might typically be provided by a web container. This implementation looks up the JDBC DataSource using JNDI. The JNDI name of the datasource, backing table and mapped columns used by this class can be overridden by adding settings in `jspwiki.properties`.

Configurable properties are these:

Property | Default | Definition
--- | --- | ---
`jspwiki.groupdatabase.datasource` | `jdbc/GroupDatabase` | The JNDI name of the DataSource
`jspwiki.groupdatabase.table` | `groups` | The table that stores the groups
`jspwiki.groupdatabase.membertable` | `group_members` | The table that stores the names of group members
`jspwiki.groupdatabase.created` | `created` | The column containing the group's creation timestamp
`jspwiki.groupdatabase.creator` | `creator` | The column containing the group creator's name
`jspwiki.groupdatabase.name` | `name` | The column containing the group's name
`jspwiki.groupdatabase.member` | `member` | The column containing the group member's name
`jspwiki.groupdatabase.modified` | `modified` | The column containing the group's last-modified timestamp
`jspwiki.groupdatabase.modifier` | `modifier` | The column containing the name of the user who last modified the group

This class is typically used in conjunction with a web container's JNDI resource factory. For example, Tomcat versions 4 and higher provide a basic JNDI factory for registering DataSources. To give JSPWiki access to the JNDI resource named by `jdbc/GroupDatabase`, you would declare the datasource resource similar to this:

> `<Context ...>
> ...
> <Resource name="jdbc/GroupDatabase" auth="Container"
> type="javax.sql.DataSource" username="dbusername" password="dbpassword"
> driverClassName="org.hsql.jdbcDriver" url="jdbc:HypersonicSQL:database"
> maxActive="8" maxIdle="4"/>
> ...
> </Context>`

JDBC driver JARs should be added to Tomcat's `common/lib` directory. For more Tomcat 5.5 JNDI configuration examples, see http://tomcat.apache.org/tomcat-5.5-doc/jndi-resources-howto.html.

JDBCGroupDatabase commits changes as transactions if the back-end database supports them. Changes are made immediately (during the `save(Group, Principal)` method).

Since:
  2.3

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`DEFAULT_GROUPDB_CREATED`
Default column name that stores the the group creation timestamps.
`static final String`
`DEFAULT_GROUPDB_CREATOR`
Default column name that stores group creator names.
`static final String`
`DEFAULT_GROUPDB_DATASOURCE`
Default column name that stores the JNDI name of the DataSource.
`static final String`
`DEFAULT_GROUPDB_MEMBER`
Default column name that stores group member names.
`static final String`
`DEFAULT_GROUPDB_MEMBER_TABLE`
Default column name that stores the names of group members.
`static final String`
`DEFAULT_GROUPDB_MODIFIED`
Default column name that stores group last-modified timestamps.
`static final String`
`DEFAULT_GROUPDB_MODIFIER`
Default column name that stores names of users who last modified groups.
`static final String`
`DEFAULT_GROUPDB_NAME`
Default column name that stores the group names.
`static final String`
`DEFAULT_GROUPDB_TABLE`
Default table name for the table that stores groups.
`protected static final org.apache.logging.log4j.Logger`
`LOG`
`static final String`
`PROP_GROUPDB_CREATED`
The column containing the group's creation timestamp.
`static final String`
`PROP_GROUPDB_CREATOR`
The column containing the group creator's name.
`static final String`
`PROP_GROUPDB_DATASOURCE`
The JNDI name of the DataSource.
`static final String`
`PROP_GROUPDB_MEMBER`
The column containing the group member's name.
`static final String`
`PROP_GROUPDB_MEMBER_TABLE`
The table that stores the names of group members.
`static final String`
`PROP_GROUPDB_MODIFIED`
The column containing the group's last-modified timestamp.
`static final String`
`PROP_GROUPDB_MODIFIER`
The column containing the name of the user who last modified the group.
`static final String`
`PROP_GROUPDB_NAME`
The column containing the group's name.
`static final String`
`PROP_GROUPDB_TABLE`
The table that stores the groups.

## Constructor Summary

Constructors
Constructor
Description
`JDBCGroupDatabase()`

## Method Summary

Modifier and Type
Method
Description
`void`
`delete(Group group)`
Looks up and deletes a `Group` from the group database.
`Group[]`
`groups()`
Returns all wiki groups that are stored in the GroupDatabase as an array of Group objects.
`void`
`initialize(Engine engine, Properties props)`
Initializes the group database based on values from a Properties object.
`void`
`save(Group group, Principal modifier)`
Saves a Group to the group database.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### DEFAULT_GROUPDB_DATASOURCE

public static final String DEFAULT_GROUPDB_DATASOURCE
Default column name that stores the JNDI name of the DataSource.

See Also:
  - Constant Field Values

### DEFAULT_GROUPDB_TABLE

public static final String DEFAULT_GROUPDB_TABLE
Default table name for the table that stores groups.

See Also:
  - Constant Field Values

### DEFAULT_GROUPDB_MEMBER_TABLE

public static final String DEFAULT_GROUPDB_MEMBER_TABLE
Default column name that stores the names of group members.

See Also:
  - Constant Field Values

### DEFAULT_GROUPDB_CREATED

public static final String DEFAULT_GROUPDB_CREATED
Default column name that stores the the group creation timestamps.

See Also:
  - Constant Field Values

### DEFAULT_GROUPDB_CREATOR

public static final String DEFAULT_GROUPDB_CREATOR
Default column name that stores group creator names.

See Also:
  - Constant Field Values

### DEFAULT_GROUPDB_NAME

public static final String DEFAULT_GROUPDB_NAME
Default column name that stores the group names.

See Also:
  - Constant Field Values

### DEFAULT_GROUPDB_MEMBER

public static final String DEFAULT_GROUPDB_MEMBER
Default column name that stores group member names.

See Also:
  - Constant Field Values

### DEFAULT_GROUPDB_MODIFIED

public static final String DEFAULT_GROUPDB_MODIFIED
Default column name that stores group last-modified timestamps.

See Also:
  - Constant Field Values

### DEFAULT_GROUPDB_MODIFIER

public static final String DEFAULT_GROUPDB_MODIFIER
Default column name that stores names of users who last modified groups.

See Also:
  - Constant Field Values

### PROP_GROUPDB_DATASOURCE

public static final String PROP_GROUPDB_DATASOURCE
The JNDI name of the DataSource.

See Also:
  - Constant Field Values

### PROP_GROUPDB_TABLE

public static final String PROP_GROUPDB_TABLE
The table that stores the groups.

See Also:
  - Constant Field Values

### PROP_GROUPDB_MEMBER_TABLE

public static final String PROP_GROUPDB_MEMBER_TABLE
The table that stores the names of group members.

See Also:
  - Constant Field Values

### PROP_GROUPDB_CREATED

public static final String PROP_GROUPDB_CREATED
The column containing the group's creation timestamp.

See Also:
  - Constant Field Values

### PROP_GROUPDB_CREATOR

public static final String PROP_GROUPDB_CREATOR
The column containing the group creator's name.

See Also:
  - Constant Field Values

### PROP_GROUPDB_NAME

public static final String PROP_GROUPDB_NAME
The column containing the group's name.

See Also:
  - Constant Field Values

### PROP_GROUPDB_MEMBER

public static final String PROP_GROUPDB_MEMBER
The column containing the group member's name.

See Also:
  - Constant Field Values

### PROP_GROUPDB_MODIFIED

public static final String PROP_GROUPDB_MODIFIED
The column containing the group's last-modified timestamp.

See Also:
  - Constant Field Values

### PROP_GROUPDB_MODIFIER

public static final String PROP_GROUPDB_MODIFIER
The column containing the name of the user who last modified the group.

See Also:
  - Constant Field Values

### LOG

protected static final org.apache.logging.log4j.Logger LOG

## Constructor Details

### JDBCGroupDatabase

public JDBCGroupDatabase()

## Method Details

### delete

public void delete(Group group) throws WikiSecurityException
Looks up and deletes a `Group` from the group database. If the group database does not contain the supplied Group. this method throws a `NoSuchPrincipalException`. The method commits the results of the delete to persistent storage.

Specified by:
  `delete` in interface `GroupDatabase`
Parameters:
  `group` - the group to remove
Throws:
  `WikiSecurityException` - if the database does not contain the supplied group (thrown as `NoSuchPrincipalException`) or if the commit did not succeed

### groups

public Group[] groups() throws WikiSecurityException
Returns all wiki groups that are stored in the GroupDatabase as an array of Group objects. If the database does not contain any groups, this method will return a zero-length array. This method causes back-end storage to load the entire set of group; thus, it should be called infrequently (e.g., at initialization time).

Specified by:
  `groups` in interface `GroupDatabase`
Returns:
  the wiki groups
Throws:
  `WikiSecurityException` - if the groups cannot be returned by the back-end

### save

public void save(Group group, Principal modifier) throws WikiSecurityException
Saves a Group to the group database. Note that this method must fail, and throw an `IllegalArgumentException`, if the proposed group is the same name as one of the built-in Roles: e.g., Admin, Authenticated, etc. The database is responsible for setting create/modify timestamps, upon a successful save, to the Group. The method commits the results of the delete to persistent storage.

Specified by:
  `save` in interface `GroupDatabase`
Parameters:
  `group` - the Group to save
  `modifier` - the user who saved the Group
Throws:
  `WikiSecurityException` - if the Group could not be saved successfully

### initialize

public void initialize(Engine engine, Properties props) throws NoRequiredPropertyException, WikiSecurityException
Initializes the group database based on values from a Properties object.

Specified by:
  `initialize` in interface `GroupDatabase`
Parameters:
  `engine` - the wiki engine
  `props` - the properties used to initialize the group database
Throws:
  `WikiSecurityException` - if the database could not be initialized successfully
  `NoRequiredPropertyException` - if a required property is not present