fuego.papi
Class ProcessService

java.lang.Object
  fuego.papi.ProcessService

public abstract class ProcessService
extends Object

Main class in Process API (PAPI) framework.

This service provides the connection with the ALBPM Engine. The main use of ProcessService is to create a ProcessServiceSession

Example.

        // Creates the properties to create the ProcessService.
        java.util.Properties properties = new java.util.Properties();

        // Set the directory Id that we use.
        properties.setProperty(ProcessService.DIRECTORY_ID, "OrgDirectory");

        // Set the directory file that we use, this file is in the classpath.
        // The directory properties can either be in the classpath, or be a file location.
        properties.setProperty(ProcessService.DIRECTORY_PROPERTIES_RESOURCE, "directory.properties");

        // Set the maximum size of the instance cache per process.
        properties.setProperty(ProcessService.INSTANCE_CACHE_SIZE, "50000");

        // Set the folder where PAPI will store catalogs and temporary files.
        properties.setProperty(ProcessService.WORKING_FOLDER, "/fuego/tmp");

        // Set that the sessions will be notified when an instance is updated.
        properties.setProperty(ProcessService.UPDATE_SESSIONS_VIEWS, "true");

        // Creates the ProcessService.
        ProcessService processService = ProcessService.create(properties);

        // Creates the passport for the user which will connect.
        ConnectionPassport passport = processService.createPassport("userId);

        // Sets the passpord of the user.
        passport.setPassword("userPassport");

        // Fills the passport
        passport.fillPassport();

        // Creates a new session.
        // The arguments are the passport of the user and the host where the user is connected from.
        ProcessServiceSession session = processService.createSession(passport, "userHost");
 

Nested Class Summary

static interface

ProcessService.Factory

Field Summary

static int	DEFAULT_CACHE_SIZE Deprecated. use DEFAULT_INSTANCE_CACHE_SIZE instead
static String	DEFAULT_DIRECTORY_ID Default value for the property key DIRECTORY_ID.
static String	DEFAULT_DIRECTORY_PROPERTIES_FILE Default value for the property key DIRECTORY_PROPERTIES_FILE.
static String	DEFAULT_DOCUMENTATION_FOLDER Default value for the property key DOCUMENTATION_FOLDER.
static int	DEFAULT_INSTANCE_CACHE_SIZE Default value for the property key INSTANCES_CACHE_SIZE.
static String	DEFAULT_USER_DOCUMENTATION_FOLDER Deprecated. user DEFAULT_DOCUMENTATION_FOLDER instead
static String	DEFAULT_WORKING_DIRECTORY Deprecated. use DEFAULT_WORKING_FOLDER instead
static String	DEFAULT_WORKING_FOLDER Default value for the property key WORKING_FOLDER.
static String	DIRECTORY_ID Property key for Directory Identifier.
static String	DIRECTORY_PROPERTIES_FILE Property key for the location of the directory.properties file.
static String	DIRECTORY_PROPERTIES_RESOURCE Property key for the filename of the directory.properties resource.
static String	DIRECTORY_PROPERTIES_URL Property key for the URL of the directory.properties resource.
static String	DOCUMENTATION_FOLDER Property key for the folder for storing process documentation.
static String	INSTANCES_CACHE_SIZE Property key for instances cache size.
static String	UPDATE_SESSIONS_VIEWS Deprecated. all views are updated when an instance is updated.
static String	USER_DOCUMENTATION_FOLDER Deprecated. use DOCUMENTATION_FOLDER instead
static String	WORKING_FOLDER Property key for working folder.

Constructor Summary

ProcessService()

Method Summary

abstract void	authenticatePassport(ConnectionPassport connectionPassport) Authenticate a participant using a ConnectionPassport with user credentials.
abstract void	close() Closes this service, disconnects all the sessions that are still connected, and removes all temporary files.
static ProcessService	create(ConnectionPassport passport, Properties properties) Creates a new ProcessService using ConnectionPassport and Properties. You do not need to set the directory properties because the passport contains that information. The directory properties include: ProcessService.DIRECTORY_ID ProcessService.DIRECTORY_PROPERTIES_FILE ProcessService.DIRECTORY_PROPERTIES_RESOURCE ProcessService.DIRECTORY_PROPERTIES_URL
static ProcessService	create(Properties properties) Recommended method to create a ProcessService.
static Filter	createFilter() Creates a Filter for use in getting InstanceInfo.
abstract ConnectionPassport	createPassport(String participant) Creates a ConnectionPassport to connect to the process service using a participant id. The participant can be null, representing an anonymous connection.
abstract ConnectionPassport	createPassportWithPreset(String preset) Creates a ConnectionPassport to connect to the process service using the preset connection information from the directory properties.
abstract ProcessServiceSession	createSession(ConnectionPassport passport, String host) Creates a ProcessServiceSession using ConnectionPassport and the user's host.
abstract ProcessServiceSession	createSession(String userId, String password, String host) Creates a ProcessServiceSession using a user id, password, and the user's host.
abstract fuego.papi.attachment.runtime.AttachmentConfigRetriever	getAttachmentConfigRetriever() Obtains a AttachmentConfigRetriever.
abstract Properties	getProperties() Returns the properties used to create this object.
abstract String	getProperty(String propertyKey) Returns the value of the given property key from the properties that was used to create this ProcessService. The property should be one of the default property values, e.g.
abstract String	getUserDocumentationFolder() Gets the user documentation folder.
static char[]	invalidIdCharacters() Returns an array of characters that are invalid for identifiers, including view and presentation identifiers. This list is not exhaustive; id characters cannot be non-ascii characters.
abstract void	setLocale(Locale locale, ProcessServiceSession session) Sets the locale for messages from the engine.
abstract void	setUserDocumentationFolder(String userDocumentationFolder) Deprecated. use DOCUMENTATION_FOLDER property.
abstract void	startUpdater(ConnectionPassport passport, long updateFrequency) Starts the updater to synchronize directory changes for views, presentations, variable definitions and groups.
abstract void	startUpdater(long updateFrequency) Starts the updater to synchronize directory changes for views, presentations, variable definitions and groups.
abstract void	stopUpdater() Stops the updater.
abstract String	toString() Returns information about the directory url, working folder, and number of active sessions.
static void	updateOrganizationalInformationFromDirectory() Synchronizes directory changes for views, presentations, varible definitions and groups. The operation will be executed only if you started the updater startUpdater(fuego.lang.ConnectionPassport, long).

Methods inherited from class java.lang.Object

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

Field Detail

DIRECTORY_PROPERTIES_FILE

@NonNls
public static final String DIRECTORY_PROPERTIES_FILE

Property key for the location of the directory.properties file.

See Also:

Constant Field Values

DIRECTORY_PROPERTIES_RESOURCE

@NonNls
public static final String DIRECTORY_PROPERTIES_RESOURCE

Property key for the filename of the directory.properties resource. This assumes that the directory.properties file is in the classpath.

See Also:

Constant Field Values

DIRECTORY_PROPERTIES_URL

@NonNls
public static final String DIRECTORY_PROPERTIES_URL

Property key for the URL of the directory.properties resource.

See Also:

Constant Field Values

DIRECTORY_ID

@NonNls
public static final String DIRECTORY_ID

Property key for Directory Identifier.

See Also:

Constant Field Values

INSTANCES_CACHE_SIZE

@NonNls
public static final String INSTANCES_CACHE_SIZE

Property key for instances cache size. Instances cache size is per process.

See Also:

Constant Field Values

UPDATE_SESSIONS_VIEWS

@Deprecated
@NonNls
public static final String UPDATE_SESSIONS_VIEWS

Deprecated. all views are updated when an instance is updated.

Property key for notifies sessions when an instance is updated.
The valid values are "true" and "false".

See Also:

Constant Field Values

WORKING_FOLDER

@NonNls
public static final String WORKING_FOLDER

Property key for working folder. The working folder is where PAPI will download process catalogs.

See Also:

Constant Field Values

USER_DOCUMENTATION_FOLDER

@Deprecated
@NonNls
public static final String USER_DOCUMENTATION_FOLDER

Deprecated. use DOCUMENTATION_FOLDER instead

Property key for the folder for storing process documentation.

See Also:

Constant Field Values

DOCUMENTATION_FOLDER

@NonNls
public static final String DOCUMENTATION_FOLDER

Property key for the folder for storing process documentation.

See Also:

Constant Field Values

DEFAULT_CACHE_SIZE

@Deprecated
public static final int DEFAULT_CACHE_SIZE

Deprecated. use DEFAULT_INSTANCE_CACHE_SIZE instead

Default value for the property key INSTANCES_CACHE_SIZE.

See Also:

Constant Field Values

DEFAULT_INSTANCE_CACHE_SIZE

public static final int DEFAULT_INSTANCE_CACHE_SIZE

Default value for the property key INSTANCES_CACHE_SIZE.

See Also:

Constant Field Values

DEFAULT_WORKING_DIRECTORY

@Deprecated
@NonNls
public static final String DEFAULT_WORKING_DIRECTORY

Deprecated. use DEFAULT_WORKING_FOLDER instead

Default value for the property key WORKING_FOLDER.

See Also:

Constant Field Values

DEFAULT_WORKING_FOLDER

@NonNls
public static final String DEFAULT_WORKING_FOLDER

Default value for the property key WORKING_FOLDER.

See Also:

Constant Field Values

DEFAULT_USER_DOCUMENTATION_FOLDER

@Deprecated
@NonNls
public static final String DEFAULT_USER_DOCUMENTATION_FOLDER

Deprecated. user DEFAULT_DOCUMENTATION_FOLDER instead

Default value for the property key DOCUMENTATION_FOLDER.

See Also:

Constant Field Values

DEFAULT_DOCUMENTATION_FOLDER

@NonNls
public static final String DEFAULT_DOCUMENTATION_FOLDER

Default value for the property key DOCUMENTATION_FOLDER.

See Also:

Constant Field Values

DEFAULT_DIRECTORY_ID

@NonNls
public static final String DEFAULT_DIRECTORY_ID

Default value for the property key DIRECTORY_ID.

See Also:

Constant Field Values

DEFAULT_DIRECTORY_PROPERTIES_FILE

@NonNls
public static final String DEFAULT_DIRECTORY_PROPERTIES_FILE

Default value for the property key DIRECTORY_PROPERTIES_FILE.

See Also:

Constant Field Values

Constructor Detail

ProcessService

public ProcessService()

Method Detail

close

public abstract void close()

Closes this service, disconnects all the sessions that are still connected, and removes all temporary files.

createPassport

public abstract ConnectionPassport createPassport(String participant)

Creates a ConnectionPassport to connect to the process service using a participant id.
The participant can be null, representing an anonymous connection.

Parameters:

participant - id of participant or null for anonymous connection.

Returns:

ConnectionPassword used to connect to ProcessService for participant.

createPassportWithPreset

public abstract ConnectionPassport createPassportWithPreset(String preset)

Creates a ConnectionPassport to connect to the process service using the preset connection information from the directory properties.

Parameters:

preset - the name which describe the scope of the set of properties.

Returns:

ConnectionPassword used to connect to ProcessService with preset information from the directory.properties file.

createSession

public abstract ProcessServiceSession createSession(ConnectionPassport passport,
                                                    @NonNls
                                                    String host)
                                             throws OperationException

Creates a ProcessServiceSession using ConnectionPassport and the user's host.

Parameters:

passport - ConnectionPassport with user credentials. Cannot be null.

host - where the user is connected from. Cannot be null.

Returns:

ProcessServiceSession The created session for the specified passport.

Throws:

OperationException - may be one of the following subclasses of OperationException:

AuthenticationException if the user in the connectionpassport could not be authenticated against the directory server.

ProtocolNotSupportedException if the protocol specified in the directory.properties key directory.default.url is not supported.

CommunicationException if unable to connect to the directory.

ParticipantNotFoundException if the user cannot be found.

AbsentParticipantException if the participant is absent as defined by the participant's Absence Periods.

See Also:

createPassport(String)

createSession

public abstract ProcessServiceSession createSession(String userId,
                                                    String password,
                                                    String host)
                                             throws OperationException

Creates a ProcessServiceSession using a user id, password, and the user's host.

Parameters:

userId - user id. Cannot be null.

password - user Password. Cannot be null.

host - where the user is connected from. Cannot be null.

Returns:

ProcessServiceSession The created session.

Throws:

OperationException - - OperationException may be one of the following subclasses of OperationException:
AuthenticationException if the user in the connectionpassport could not be authenticated against the directory server.
ProtocolNotSupportedException if the protocol specified in the directory.properties key directory.default.url is not supported.
CommunicationException if unable to connect to the directory.
ParticipantNotFoundException if the user cannot be found.
AbsentParticipantException if the participant is absent as defined by the participant's Absence Periods.

See Also:

createPassport(String)

getUserDocumentationFolder

public abstract String getUserDocumentationFolder()

Gets the user documentation folder.

Returns:

User documentation folder.

See Also:

setUserDocumentationFolder(String)

setLocale

public abstract void setLocale(Locale locale,
                               ProcessServiceSession session)
                        throws OperationException

Sets the locale for messages from the engine.

Parameters:

locale - locale to use for messages. Cannnot be null.

session - session to set locale.

Throws:

OperationException - If the service could not perform the operation.

setUserDocumentationFolder

@Deprecated
public abstract void setUserDocumentationFolder(String userDocumentationFolder)

Deprecated. use DOCUMENTATION_FOLDER property.

Sets the user documentation folder (Folder where the documentation will be stored).

Parameters:

userDocumentationFolder - full path to directory to use for the root user documentation folder. Cannot be null.

startUpdater

public abstract void startUpdater(long updateFrequency)
                           throws OperationException

Starts the updater to synchronize directory changes for views, presentations, variable definitions and groups.

Parameters:

updateFrequency - frequency to synchronize objects, in milliseconds.

Throws:

OperationException - if an error occured when starting the updater.

startUpdater

public abstract void startUpdater(ConnectionPassport passport,
                                  long updateFrequency)
                           throws OperationException

Starts the updater to synchronize directory changes for views, presentations, variable definitions and groups.

Parameters:

passport - passport used to to create a new session for synchronization. Cannot be null

updateFrequency - frequency to synchronize objects, in milliseconds.

Throws:

OperationException - if an error occured when starting the updater.

See Also:

createPassport(String)

stopUpdater

public abstract void stopUpdater()
                          throws OperationException

Stops the updater. Has no effect if the updater was not previously started.

Throws:

OperationException - if an error occured when stopping the updater.

toString

public abstract String toString()

Returns information about the directory url, working folder, and number of active sessions.

Overrides:

toString in class Object

Returns:

information about the directory url, working folder, and number of active sessions.

getProperties

public abstract Properties getProperties()

Returns the properties used to create this object.

Returns:

Properties used to create this object.

getProperty

public abstract String getProperty(String propertyKey)

Returns the value of the given property key from the properties that was used to create this ProcessService.
The property should be one of the default property values, e.g. DIRECTORY_PROPERTIES_RESOURCE, or any property that you used when create this ProcessService, e.g. "MyProperties.MyKey".

Parameters:

propertyKey - the key of the property to obtain.

Returns:

the corresponding property value or null if the specified property does not exist.

authenticatePassport

public abstract void authenticatePassport(ConnectionPassport connectionPassport)
                                   throws OperationException

Authenticate a participant using a ConnectionPassport with user credentials.

Parameters:

connectionPassport - ConnectionPassport with user credentials. Cannot be null.

Throws:

OperationException - may be one of the following subclasses of OperationException:

AuthenticationException if the user in the connectionpassport could not be authenticated against the directory server.

ProtocolNotSupportedException if the protocol specified in the directory.properties key directory.default.url is not supported.

CommunicationException if unable to connect to the directory.

ParticipantNotFoundException if the user cannot be found.

getAttachmentConfigRetriever

public abstract fuego.papi.attachment.runtime.AttachmentConfigRetriever getAttachmentConfigRetriever()

Obtains a AttachmentConfigRetriever.

Returns:

The AttachmentConfigRetriever created for this ProcessService.

create

public static ProcessService create(Properties properties)
                             throws CommunicationException

Recommended method to create a ProcessService.

Parameters:

properties - the properties to create the new ProcessService. Cannot be null.
Includes the following keys:

• ProcessService.DIRECTORY_ID, which is usually set to ProcessService.DEFAULT_DIRECTORY_ID;
• ProcessService.DIRECTORY_PROPERTIES_FILE, which is set to the absolute or relative location of the directory.properties file or ProcessService.DIRECTORY_PROPERTIES_RESOURCE, which is set to the name of the directory.properties file in the classpath or ProcessService.DIRECTORY_PROPERTIES_URL, which is set to the url of the directory.properties file;
• ProcessService.INSTANCES_CACHE_SIZE, which can be set to a default value of ProcessService.DEFAULT_CACHE_SIZE,
• ProcessService.WORKING_FOLDER, which is generally set to ProcessService.DEFAULT_WORKING_DIRECTORY.

If an empty properties object is passed, the default values will be used.

Returns:

ProcessService

Throws:

CommunicationException - if unable to communicate with the directory.

create

public static ProcessService create(ConnectionPassport passport,
                                    Properties properties)
                             throws CommunicationException

Creates a new ProcessService using ConnectionPassport and Properties.
You do not need to set the directory properties because the passport contains that information.
The directory properties include:

• ProcessService.DIRECTORY_ID
• ProcessService.DIRECTORY_PROPERTIES_FILE
• ProcessService.DIRECTORY_PROPERTIES_RESOURCE
• ProcessService.DIRECTORY_PROPERTIES_URL

Parameters:

passport - Connection passport used to get the values for the directory (Directory Id and directory properties).

properties - The properties to create the new ProcessService.

Returns:

ProcessService.

Throws:

CommunicationException - if unable to communicate with the directory.

See Also:

createPassport(String)

createFilter

public static Filter createFilter()

Creates a Filter for use in getting InstanceInfo. Filters can be used to get instances directly using ProcessServiceNESession.getInstancesByFilter, or can be applied to an EditableInstancesView to filter the instances returned.

Returns:

Filter for use in getting InstanceInfo.

See Also:

ProcessServiceSession.processesGetInstancesByFilter(fuego.papi.collections.ProcessIdSet, Filter)

invalidIdCharacters

public static char[] invalidIdCharacters()

Returns an array of characters that are invalid for identifiers, including view and presentation identifiers.
This list is not exhaustive; id characters cannot be non-ascii characters.

Returns:

array of invalid id characters.

updateOrganizationalInformationFromDirectory

public static void updateOrganizationalInformationFromDirectory()

Synchronizes directory changes for views, presentations, varible definitions and groups.
The operation will be executed only if you started the updater startUpdater(fuego.lang.ConnectionPassport, long).