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 java.lang.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
`static java.lang.String` `DEFAULT_GROUPDB_CREATED` Default column name that stores the the group creation timestamps.
`static java.lang.String` `DEFAULT_GROUPDB_CREATOR` Default column name that stores group creator names.
`static java.lang.String` `DEFAULT_GROUPDB_DATASOURCE` Default column name that stores the JNDI name of the DataSource.
`static java.lang.String` `DEFAULT_GROUPDB_MEMBER` Default column name that stores group member names.
`static java.lang.String` `DEFAULT_GROUPDB_MEMBER_TABLE` Default column name that stores the names of group members.
`static java.lang.String` `DEFAULT_GROUPDB_MODIFIED` Default column name that stores group last-modified timestamps.
`static java.lang.String` `DEFAULT_GROUPDB_MODIFIER` Default column name that stores names of users who last modified groups.
`static java.lang.String` `DEFAULT_GROUPDB_NAME` Default column name that stores the group names.
`static java.lang.String` `DEFAULT_GROUPDB_TABLE` Default table name for the table that stores groups.
`protected static org.apache.logging.log4j.Logger` `LOG`
`static java.lang.String` `PROP_GROUPDB_CREATED` The column containing the group's creation timestamp.
`static java.lang.String` `PROP_GROUPDB_CREATOR` The column containing the group creator's name.
`static java.lang.String` `PROP_GROUPDB_DATASOURCE` The JNDI name of the DataSource.
`static java.lang.String` `PROP_GROUPDB_MEMBER` The column containing the group member's name.
`static java.lang.String` `PROP_GROUPDB_MEMBER_TABLE` The table that stores the names of group members.
`static java.lang.String` `PROP_GROUPDB_MODIFIED` The column containing the group's last-modified timestamp.
`static java.lang.String` `PROP_GROUPDB_MODIFIER` The column containing the name of the user who last modified the group.
`static java.lang.String` `PROP_GROUPDB_NAME` The column containing the group's name.
`static java.lang.String` `PROP_GROUPDB_TABLE` The table that stores the groups.

### Constructor Summary

Constructors
`JDBCGroupDatabase()`

### Method Summary

All Methods Instance Methods Concrete Methods
`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, java.util.Properties props)` Initializes the group database based on values from a Properties object.
`void` `save​(Group group, java.security.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 Detail

#### DEFAULT_GROUPDB_DATASOURCE

    public static final java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.String DEFAULT_GROUPDB_CREATOR

Default column name that stores group creator names.

See Also:
  Constant Field Values

#### DEFAULT_GROUPDB_NAME

    public static final java.lang.String DEFAULT_GROUPDB_NAME

Default column name that stores the group names.

See Also:
  Constant Field Values

#### DEFAULT_GROUPDB_MEMBER

    public static final java.lang.String DEFAULT_GROUPDB_MEMBER

Default column name that stores group member names.

See Also:
  Constant Field Values

#### DEFAULT_GROUPDB_MODIFIED

    public static final java.lang.String DEFAULT_GROUPDB_MODIFIED

Default column name that stores group last-modified timestamps.

See Also:
  Constant Field Values

#### DEFAULT_GROUPDB_MODIFIER

    public static final java.lang.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 java.lang.String PROP_GROUPDB_DATASOURCE

The JNDI name of the DataSource.

See Also:
  Constant Field Values

#### PROP_GROUPDB_TABLE

    public static final java.lang.String PROP_GROUPDB_TABLE

The table that stores the groups.

See Also:
  Constant Field Values

#### PROP_GROUPDB_MEMBER_TABLE

    public static final java.lang.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 java.lang.String PROP_GROUPDB_CREATED

The column containing the group's creation timestamp.

See Also:
  Constant Field Values

#### PROP_GROUPDB_CREATOR

    public static final java.lang.String PROP_GROUPDB_CREATOR

The column containing the group creator's name.

See Also:
  Constant Field Values

#### PROP_GROUPDB_NAME

    public static final java.lang.String PROP_GROUPDB_NAME

The column containing the group's name.

See Also:
  Constant Field Values

#### PROP_GROUPDB_MEMBER

    public static final java.lang.String PROP_GROUPDB_MEMBER

The column containing the group member's name.

See Also:
  Constant Field Values

#### PROP_GROUPDB_MODIFIED

    public static final java.lang.String PROP_GROUPDB_MODIFIED

The column containing the group's last-modified timestamp.

See Also:
  Constant Field Values

#### PROP_GROUPDB_MODIFIER

    public static final java.lang.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 Detail

#### JDBCGroupDatabase

    public JDBCGroupDatabase()

### Method Detail

#### 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,
                     java.security.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,
                           java.util.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