filenet.vw.api

Class VWRosterDefinition

java.lang.Object

filenet.vw.api.VWTableDefinition

filenet.vw.api.VWRosterDefinition

All Implemented Interfaces:

IVWTableDefinition, IVWtoXML, java.io.Serializable, java.lang.Cloneable

public final class VWRosterDefinition
extends VWTableDefinition
implements java.io.Serializable, IVWTableDefinition, java.lang.Cloneable, IVWtoXML

Use the VWRosterDefinition.java class to retrieve and administer roster definition information. The methods of this class operate in conjunction with VWSystemConfiguration class methods as follows:

• VWSystemConfiguration.createRosterDefinition(String) returns a default roster definition.
• VWSystemConfiguration.updateRosterDefinition(VWRosterDefinition) uses this VWRosterDefinition object to update a roster definition.
• VWSystemConfiguration.getRosterDefinitions() returns an array of the roster definitions associated with this system configuration.
• VWSystemConfiguration.commit() saves roster definition changes to the server.

Methods for Managing User and Group Access Control

This class contains the following access control methods that input VWParticipant objects:

• VWRosterDefinition.setCreateSecurityPx(VWParticipant[])
• VWRosterDefinition.setReadSecurityPx(VWParticipant[])
• VWRosterDefinition.setWriteSecurityPx(VWParticipant[])

After the above methods have been used to set access permissions (using VWParticipant object arrays), the following methods should be used to retrieve (get) VWParticipant arrays that represent users and groups who have create, read, or write access:

• VWParticipant[] VWRosterDefinition.getCreateSecurityPx()
• VWParticipant[] VWRosterDefinition.getReadSecurityPx()
• VWParticipant[] VWRosterDefinition.getWriteSecurityPx()

Note: VWParticipant objects are useful for representing user and group lists in a multi-platform environment. If VWParticipant objects are not needed, String arrays of user and group names may be used to represent users and groups, with additional methods in this class. You can set access permissions using String lists to represent users and groups with the following methods:

• VWRosterDefinition.setReadSecurity(String[])
• VWRosterDefinition.setWriteSecurity(String[])
• VWRosterDefinition.setCreateSecurity(String[])

After the above methods have been used to set access permissions (using VWParticipant object arrays), the following methods should be used to retrieve (get) String arrays that represent users and groups who have create, read, or write access:

• String[] VWRosterDefinition.getReadSecurity()
• String[] VWRosterDefinition.getWriteSecurity()
• String[] VWRosterDefinition.getCreateSecurity()

Since:

VWWS3.10

See Also:

VWParticipant, VWSystemConfiguration, Serialized Form

Field Summary

Fields inherited from class filenet.vw.api.VWTableDefinition

CONFIG_TYPE_LOG, CONFIG_TYPE_QUEUE, CONFIG_TYPE_ROSTER, IWFCaseFolder, IWFCaseTask, LVALUE, RVALUE

Method Summary

Modifier and Type	Method and Description
java.lang.Object	clone() Creates a clone of this VWRosterDefinition object.
VWExposedFieldDefinition	createFieldDefinition(java.lang.String theName, int theType, int theLength) Creates an exposed field on the roster, based on the supplied field name and type.
void	createFieldDefinitions(VWExposedFieldDefinition[] theDefs) Creates the complete field definition for this roster.
VWIndexDefinition	createIndexDefinition(java.lang.String theName, java.lang.String[] theFieldNames) Creates an index definition for the roster.
void	createIndexDefinitions(VWIndexDefinition[] theDefs) Creates the complete index definition for this roster.
void	deleteFieldDefinition(java.lang.String theName) Deletes an exposed field from the roster.
void	deleteIndexDefinition(java.lang.String theName) Deletes an index from this roster.
java.lang.String[]	getCreateSecurity() Returns a list of users and/or groups who have create access to the roster.
VWParticipant[]	getCreateSecurityPx() Returns an array of VWParticipant objects that names the users and/or groups who have create access to the roster.
java.lang.String	getDescription() Returns the description for this roster.
VWExposedFieldDefinition	getField(java.lang.String name) Returns the field definition for the specified exposed field in this roster.
VWIndexDefinition	getIndex(java.lang.String name) Get an index definition specified for this roster definition.
java.lang.String	getName() Gets the authored name of this roster.
java.lang.String[]	getReadSecurity() Lists the users and/or groups who currently have read access to the roster.
VWParticipant[]	getReadSecurityPx() Returns an array VWParticipant objects that specifies the users and/or groups who currently have read access to the roster.
int	getServerId() Gets the home server ID of this roster definition.
java.lang.String[]	getWriteSecurity() Lists users and/or groups who have write access to the roster.
VWParticipant[]	getWriteSecurityPx() Returns an array of VWParticipant objects for the user and/or groups who have write access to this roster.
boolean	hasChanged() Returns a boolean value indicating whether or not this roster has changed.
static VWExposedFieldDefinition[]	optionalSystemFields() Returns workflow system exposed fields that are marked as optional.
void	setCreateSecurity(java.lang.String[] theNames) Sets create access to the roster for the passed-in list of users and/or groups.
void	setCreateSecurityPx(VWParticipant[] thePxList) Sets create access on the roster for the users and/or groups specified by the passed-in array of VWParticipant objects.
void	setDescription(java.lang.String theDescription) Sets the description for this roster definition.
void	setReadSecurity(java.lang.String[] theNames) Sets read access on the roster for the passed-in list of users and/or groups.
void	setReadSecurityPx(VWParticipant[] thePxList) Sets read access privilege on this roster for the users and/or groups represented by the passed-in array of VWParticipant objects.
void	setServerId(int theNewServerId) Sets the home server ID of the roster.
void	setWriteSecurity(java.lang.String[] theNames) Sets write access to this roster for the users and/or groups specified.
void	setWriteSecurityPx(VWParticipant[] thePxList) Sets write access to the current roster for the users and / or groups specified by the passed-in array of VWParticipant objects.
java.lang.String	toString() Returns the string version of the roster definition.
void	toXML(java.lang.StringBuffer theBuffer) Deprecated. Use VWXMLConfiguration.makeXMLBlock(IVWtoXML[]).

Methods inherited from class filenet.vw.api.VWTableDefinition

getFields, getIndexes, getLocalizedString, hasFieldName, isValid, optionalSystemFields

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface filenet.vw.api.IVWTableDefinition

getFields, getIndexes

Method Detail

createFieldDefinition

public VWExposedFieldDefinition createFieldDefinition(java.lang.String theName,
                                                      int theType,
                                                      int theLength)
                                               throws VWException

Creates an exposed field on the roster, based on the supplied field name and type. Use exposed fields to create index definitions. When specifying the name for the new exposed field, the name must:

• Begin with an alphabetic character (other than "F_").
• Contain 30 or fewer characters (bytes).
• Be alphanumeric (underscores are acceptable after the first letter in the name).
• Not contain special characters.

Specified by:

createFieldDefinition in interface IVWTableDefinition

Overrides:

createFieldDefinition in class VWTableDefinition

Parameters:

theName - The name of the field to expose.

theType - An integer value indicating the data type associated with the exposed field. Note that arrays, for any of the data types, are not allowed. Valid values are as follows:

• 1: Integer (FIELD_TYPE_INT)
• 2: String (FIELD_TYPE_STRING)
• 4: Boolean (FIELD_TYPE_BOOLEAN)
• 8: Float (FIELD_TYPE_FLOAT)
• 16: Time/date (FIELD_TYPE_TIME)

theLength - An integer value specifying the length (number of bytes) of data stored if the data field is a string. If the field type is other than string, specify the 0 (zero).

Returns:

A VWExposedFieldDefinition object that contains roster definition information.

Throws:

VWException

deleteFieldDefinition

public void deleteFieldDefinition(java.lang.String theName)
                           throws VWException

Deletes an exposed field from the roster.

Specified by:

deleteFieldDefinition in interface IVWTableDefinition

Overrides:

deleteFieldDefinition in class VWTableDefinition

Parameters:

theName - The name of the exposed field to delete from the roster.

Throws:

VWException - Thrown if the field specified in the theName parameter is not found.

createFieldDefinitions

public void createFieldDefinitions(VWExposedFieldDefinition[] theDefs)
                            throws VWException

Creates the complete field definition for this roster. This is a helper function for the JNI stuff to easily add the field definitions.

Parameters:

theDefs - the array of VWExposedFieldDefinition

Throws:

VWException

createIndexDefinition

public VWIndexDefinition createIndexDefinition(java.lang.String theName,
                                               java.lang.String[] theFieldNames)
                                        throws VWException

Creates an index definition for the roster. Pass the index name and an array of system fields and/or user-defined exposed fields to create the definition of the concatenated index. Use at least one user-defined field name to create the index. When specifying the name for the index field, the name must:

• Begin with an alphabetic character (other than "F_").
• Contain 30 or fewer characters (bytes).
• Be alphanumeric (underscores are acceptable after the first letter in the name).
• Not contain special characters.

Specified by:

createIndexDefinition in interface IVWTableDefinition

Specified by:

createIndexDefinition in class VWTableDefinition

Parameters:

theName - The name of the new index field.

theFieldNames - A string array containing the system fields and/or user-defined exposed fields.

Returns:

A VWIndexDefinition object for the index definition created.

Throws:

VWException - Thrown if the system finds an error in the name or if the fields are undefined.

deleteIndexDefinition

public void deleteIndexDefinition(java.lang.String theName)
                           throws VWException

Deletes an index from this roster.

Specified by:

deleteIndexDefinition in interface IVWTableDefinition

Overrides:

deleteIndexDefinition in class VWTableDefinition

Parameters:

theName - The name of the index to be deleted from the roster.

Throws:

VWException - Thrown if the system does not find the index name.

createIndexDefinitions

public void createIndexDefinitions(VWIndexDefinition[] theDefs)
                            throws VWException

Creates the complete index definition for this roster. This is a helper function for the JNI stuff to easily add the index definitions.

Parameters:

theDefs - the array of VWIndexDefinition

Throws:

VWException

getField

public VWExposedFieldDefinition getField(java.lang.String name)
                                  throws VWException

Returns the field definition for the specified exposed field in this roster. If a translation source exists, the authored field information is translated.

Note: The translation is done only at runtime, so will not appear in design-time applications (such as the Process Designer or Configuration Console).

Parameters:

name - A String containing the field name.

Returns:

A VWExposedFieldDefinition object for the field specified. If a translation source exists, the translated field information is returned; otherwise, the authored information is returned. If the field cannot be found, null is returned.

Throws:

VWException

Since:

P8 4.0

getIndex

public VWIndexDefinition getIndex(java.lang.String name)
                           throws VWException

Get an index definition specified for this roster definition. If a translation source exists, the authored index information is translated.

Parameters:

name - A String containing the index name.

Returns:

A String containing the translated index information, if a translation source exists; otherwise the authored information is returned. If the index cannot be found, null is returned.

Throws:

VWException

Since:

P8 4.0

getName

public java.lang.String getName()

Gets the authored name of this roster.

Specified by:

getName in interface IVWTableDefinition

Overrides:

getName in class VWTableDefinition

Returns:

A String containing the authored name of this roster.

getServerId

public int getServerId()

Gets the home server ID of this roster definition.

Overrides:

getServerId in class VWTableDefinition

Returns:

An integer value that represents the home server ID for the roster.

setServerId

public void setServerId(int theNewServerId)
                 throws VWException

Sets the home server ID of the roster. Server ID validation must occur after you transfer the information to the VWService.

Overrides:

setServerId in class VWTableDefinition

Parameters:

theNewServerId - An integer value to be used as the new home server ID.

Throws:

VWException - Thrown if the method cannot set the home server ID of the roster.

See Also:

VWSystemConfiguration.getServerIDs()

getReadSecurity

public java.lang.String[] getReadSecurity()

Lists the users and/or groups who currently have read access to the roster.

Note: Use this method in conjunction with setWriteSecurity(String[]); do not use this method with setWriteSecurityPx(VWParticipant[]). For more information see Managing User Lists and Different Types of Security.

Overrides:

getReadSecurity in class VWTableDefinition

Returns:

A list of users and groups who have read access to the roster.

getReadSecurityPx

public VWParticipant[] getReadSecurityPx()
                                  throws VWException

Returns an array VWParticipant objects that specifies the users and/or groups who currently have read access to the roster.

Note: Use this method in conjunction with setWriteSecurityPx(VWParticipant[]); do not use this method with setWriteSecurity(String[]). For more information see Managing User Lists and Different Types of Security.

Overrides:

getReadSecurityPx in class VWTableDefinition

Returns:

A list of VWParticipant objects that names users and groups who have read access to the roster.

Throws:

VWException

setReadSecurity

public void setReadSecurity(java.lang.String[] theNames)
                     throws VWException

Sets read access on the roster for the passed-in list of users and/or groups.

Notes: This method does not validate user and group information, but user and group information can be validated subsequently by the VWSystemConfiguration.commit() method.

Use this method in conjunction with setWriteSecurity(String[]); do not use this method with setWriteSecurityPx(VWParticipant[]). For more information see Managing User Lists and Different Types of Security.

Parameters:

theNames - A list of names and/or groups who are specified to have read access to the roster.

Throws:

VWException

setReadSecurityPx

public void setReadSecurityPx(VWParticipant[] thePxList)
                       throws VWException

Sets read access privilege on this roster for the users and/or groups represented by the passed-in array of VWParticipant objects.

This method does not validate user and group information, but user and group information can be validated subsequently by the VWSystemConfiguration.commit() method.

Use this method in conjunction with setWriteSecurityPx(VWParticipant[]); do not use this method with setWriteSecurity(String[]). For more information see Managing User Lists and Different Types of Security.

Parameters:

thePxList - An array of VWParticipant objects containing names of users and/or groups, specified here to receive read access on the roster.

Throws:

VWException

getWriteSecurity

public java.lang.String[] getWriteSecurity()

Lists users and/or groups who have write access to the roster.

Use this method in conjunction with VWRosterDefinition.setWriteSecurity(String[]). Do not use this method with VWRosterDefinition.setWriteSecurityPx(VWParticipant[]).

For more information see Managing User Lists and Different Types of Security.

Overrides:

getWriteSecurity in class VWTableDefinition

Returns:

A String array of names of users and/or groups who currently have write access to the roster.

getWriteSecurityPx

public VWParticipant[] getWriteSecurityPx()
                                   throws VWException

Returns an array of VWParticipant objects for the user and/or groups who have write access to this roster.

Note: Use this method in conjunction with VWRosterDefinition.setWriteSecurityPx(VWParticipant[]). Do not use this method with VWRosterDefinition.setWriteSecurity(String[]).

For more information see Managing User Lists and Different Types of Security.

Overrides:

getWriteSecurityPx in class VWTableDefinition

Returns:

An array of VWParticipant objects containing the names of users and/or groups who have write access to this roster.

Throws:

VWException

setWriteSecurity

public void setWriteSecurity(java.lang.String[] theNames)
                      throws VWException

Sets write access to this roster for the users and/or groups specified.

Notes: This method does not validate user and group information, but user and group information can be validated subsequently by the VWSystemConfiguration.commit() method.

Use this method in conjunction with VWRosterDefinition.getWriteSecurity(). Do not use this method with VWRosterDefinition.getWriteSecurityPx().

For more information see Managing User Lists and Different Types of Security.

Parameters:

theNames - A String array containing the list of names and/or groups to receive write access.

Throws:

VWException

setWriteSecurityPx

public void setWriteSecurityPx(VWParticipant[] thePxList)
                        throws VWException

Sets write access to the current roster for the users and / or groups specified by the passed-in array of VWParticipant objects.

This method performs no validation, but user and group information can be validated subsequently using the VWSystemConfiguration.commit() method.

Note: Use this method in conjunction with VWRosterDefinition.getWriteSecurityPx(). Do not use this method with VWRosterDefinition.getCreateSecurity().

For more information see Managing User Lists and Different Types of Security.

Parameters:

thePxList - An array of VWParticipant objects containing a list of names, specified here to receive write access.

Throws:

VWException

getCreateSecurity

public java.lang.String[] getCreateSecurity()

Returns a list of users and/or groups who have create access to the roster.

Note: Use this method in conjunction with setCreateSecurity(String[]); do not use this method with setCreateSecurityPx(VWParticipant[]). For more information see Managing User Lists and Different Types of Security.

Returns:

A list of names and/or groups who have create access to the roster.

getCreateSecurityPx

public VWParticipant[] getCreateSecurityPx()
                                    throws VWException

Returns an array of VWParticipant objects that names the users and/or groups who have create access to the roster.

Note: Use this method in conjunction with setCreateSecurityPx(VWParticipant[]); do not use this method with setCreateSecurity(String[]). For more information see Managing User Lists and Different Types of Security.

Returns:

createSecurity Array of VWParticipant objects that name users and/or groups who have create access to the roster.

Throws:

VWException - Thrown for various causes, including when createSecurity() was used to set a different version of security control.

See Also:

VWRosterDefinition.setCreateSecurityPx(VWParticipant[])

setCreateSecurity

public void setCreateSecurity(java.lang.String[] theNames)
                       throws VWException

Sets create access to the roster for the passed-in list of users and/or groups. Performs no validation, but user and group information can be validated subsequently by the VWSystemConfiguration.commit() method.

Note: Use this method in conjunction with getCreateSecurity(); do not use this method with getCreateSecurityPx(). For more information see Managing User Lists and Different Types of Security.

Parameters:

theNames - A list of user names and/or groups who will be granted create access for the roster.

Throws:

VWException

setCreateSecurityPx

public void setCreateSecurityPx(VWParticipant[] thePxList)
                         throws VWException

Sets create access on the roster for the users and/or groups specified by the passed-in array of VWParticipant objects. Performs no validation, but user and group information can be validated subsequently by the VWSystemConfiguration.commit() method.

Note: Use this method in conjunction with getCreateSecurityPx(); do not use this method with getCreateSecurity(). For more information see Managing User Lists and Different Types of Security.

Parameters:

thePxList - An Array of VWParticipant objects specifying users and/or groups who will have create access to the roster.

Throws:

VWException

getDescription

public java.lang.String getDescription()

Returns the description for this roster. If a translation source exists, the authored description is translated.

Note: The translation is done only at runtime, so will not appear in design-time applications (such as the Process Designer or Configuration Console).

Specified by:

getDescription in interface IVWTableDefinition

Overrides:

getDescription in class VWTableDefinition

Returns:

A String containing the translated description, if a translation source exists; otherwise, the authored description is returned.

setDescription

public void setDescription(java.lang.String theDescription)

Sets the description for this roster definition.

Specified by:

setDescription in interface IVWTableDefinition

Overrides:

setDescription in class VWTableDefinition

Parameters:

theDescription - A String containing the description for this roster definition

toString

public java.lang.String toString()

Returns the string version of the roster definition.

Specified by:

toString in interface IVWTableDefinition

Overrides:

toString in class VWTableDefinition

Returns:

The roster name.

toXML

public void toXML(java.lang.StringBuffer theBuffer)
           throws VWException

Deprecated. Use VWXMLConfiguration.makeXMLBlock(IVWtoXML[]).

Appends an XML string representing this instance to the buffer specified.

Warning: This XML string is nonextensible, and cannot be modified in any way.

Specified by:

toXML in interface IVWtoXML

Parameters:

theBuffer - A StringBuffer that will be appended with the XML content.

Throws:

VWException - Thrown if the specified buffer is null.

See Also:

VWXMLConfiguration

hasChanged

public boolean hasChanged()
                   throws VWException

Returns a boolean value indicating whether or not this roster has changed.

Returns:

A value of true if this roster has changed; false otherwise.

Throws:

VWException - Thrown if an error occurs.

Since:

PE 4.5.0

optionalSystemFields

public static VWExposedFieldDefinition[] optionalSystemFields()
                                                       throws VWException

Returns workflow system exposed fields that are marked as optional. These fields can be exposed on a roster.

Returns:

An array of VWExposedFieldDefinition objects that represent the optional workflow system fields.

Throws:

VWException

clone

public java.lang.Object clone()

Creates a clone of this VWRosterDefinition object.

Overrides:

clone in class VWTableDefinition

Returns:

A clone of this object instance.