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. If the database supports transactions, group changes are saved to permanent storage only when the commit() method is called. If the database does not support transactions, then changes are made immediately (during the save(Group, Principal) method), and the commit() method no-ops. Thus, callers should always call the commit() method after saving a profile to guarantee that changes are applied.

Since:

2.3

Field Summary

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

Constructor Summary

JDBCGroupDatabase()

Method Summary

void	commit() Deprecated. there is no need to call this method because the save and delete methods contain their own commit logic
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(WikiEngine 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 Detail

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.log4j.Logger log

Constructor Detail

JDBCGroupDatabase

public JDBCGroupDatabase()

Method Detail

commit

@Deprecated
public void commit()
            throws WikiSecurityException

Deprecated. there is no need to call this method because the save and delete methods contain their own commit logic

No-op method that in previous versions of JSPWiki was intended to atomically commit changes to the user database. Now, the save(Group, Principal) and delete(Group) methods are atomic themselves.

Specified by:

commit in interface GroupDatabase

Throws:

WikiSecurityException - never...

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(WikiEngine 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