Table of Contents
- What is Enhydra Shark?
- Starting Shark
- Configuring Shark
- Setting "enginename" parameter
- Setting kernel behaviour in the case of unsatisfied split conditions
- Setting kernel to evaluate OTHERWISE conditions last
- Setting kernel for assignment creation
- Setting kernel behaviour to re-evaluate assignments at engine startup
- Setting kernel for assignment handling
- Setting kernel behaviour to fill the caches on startup
- Setting kernel behaviour for reevaluating deadline limits
- Setting kernel for sub-flow process locking
- Setting kernel and event audit mgr for persisting old event audit data
- Setting external repository folder
- Setting properties for browsing LDAP server
- Setting kernel's CallbackUtilities implementation class
- Setting kernel's ObjectFactory implementation class
- Setting kernel's ToolAgentManager implementation class
- New components and their settings in Shark.conf
- Database configuration
- Setting persitence components variable data model
- Setting application map persistence implementation
- Setting Assignment manager implementation class
- Setting Authentication manager implementation class
- Setting Caching implementation
- Setting instance persistence implementation
- Configuring DODS instance persistence implementation to delete processes when they finish
- Setting limit agent implementation
- Setting the lock master implementation
- Setting logging API implementation
- Setting participant map persistence implementation
- Setting repository persistence implementation
- Setting scripting manager implementation
- Setting script map persistence implementation
- Setting security (authorization) API implementation
- Setting tool agents
- Setting transaction manager implementation
- Setting user group implementation
- Setting User transaction factory implementation
- Setting DODS Id generator cache size(s)
- Setting CORBA parameters when deployed as CORBA service
- About data model
This is workflow engine completely based on WfMC and OMG specifications.
It is using WfMC's XML Process Definition Language (XPDL) as its native workflow definition format.
In its standard kernel implementation, shark is a library which does not create its own threads, and it can be used in many different environments (from WEB application, from swing application, deployed as CORBA service, in EJB container, ...). Our project distribution gives an example of using shark from Swing application and through CORBA, as well as from JSP client application.
It is very configurable, and all of its "internal" interfaces, as well as complete kernel could be replaced by another implementation.
It can be used from many VMs simultaneously (in cluster scenario).
Along with its POJO interface, it provides a CORBA interface through which the CORBA client applications can communicate with the shark deployed as a CORBA service.
It can be configured to use organizational structure defined on LDAP server (through the use of specific implementation of shark's UserGroup and Authentication component)
It does not use any XPDL's Extended Attributes for its execution rules.
Its interfaces allow passing of "external" transactions (used in some applications), so shark can work with this "client" transactions
It uses DODS (OR/M tool from Enhydra), which enables shark to use almost any DB system for storing information, and it can be easily configured to switch target DB vendor and/or url (it has predefined scripts, and means to automatically create appropriate tables in those DBs using Octopus - ETL tool from Enhydra)
It has implemented ToolAgent concept defined by WfMC to execute tools of automatic activities (several useful ToolAgents comes with shark)
Shark can use custom Java classes (and even interfaces or abstract classes) as process variables.
Shark can be started from a client application by configuring it first (which can be done in three different manners), and then by getting an instance of it. This is the most common way to use shark from an application:
String confFilePath="Shark.conf"; Shark.configure(confFilePath); Shark shark=Shark.getInstance();
Everything else can be done through the Shark interface.
If you want to use shark through CORBA interface, first you need to have shark CORBA server started (by using proper "run" script), and after that you can access it through the network using shark's CORBA API (you can start admin application using "runA" script to see an example). When starting server through "run" script, nameserver is automatically started on this machine.
Shark CORBA server is an example of shark library usage.
There are four different ways to configure shark:
use configure () method without parameters:
then shark is configured only from config file that is placed in its jar file. Shark that is configured in this way works with default settings, and without many internal API implementations (Caching, Authentication, UserGroup, ...).
use configure (String filePath) method:
it creates File object out of the path given in the filePath string, and calls the configure (File configFile) described next.
use configure (File configFile) method:
shark first does basic configuration based on properties given in its jar file, and then does additional configuration from the file specified. If the configuration File defines same properties as in default configuration file from the jar, these property's values will override the default ones, plus all additional properties from File/Properties will be added to shark configuration. The configuration files you are passing as a parameter actually does not need to define whole configuration, but they could just redefine some default configuration parameters (i.e. engineName, ObjectFactoryClassName, ...) and add some additional configuration parameters (i.e. AssignmentManagerClassName).
use configure (Properties props) method:
it does basically the same as previous method (in fact, the previous method converts the file content into Properties object), but it offers the possibility for client applications to use Java Properties object to configure shark.
you can use many shark instances configured differently (you just need to specify different config files/paths, or define different Property object). If you want to use several shark instances (from more than one VM) on the same DB, you should in fact ALWAYS use different configuration for "enginename" property (Also, if used from many VMs, all configurations must override the values for DODS cache sizes (must set it to zero), and CacheManagerClassName property should not exist). This is because of synchronization of process execution - if one VM performs an operation on a process, it is locked by this instance of Shark (which is identified by "enginename" property), so that it can't be used from other VMs until the one that locked it finishes with its work.
As already mentioned, shark is very configurable engine, and all of its components, including kernel, can be replaced by a custom implementation.
The most common way for configuring shark is defining custom Shark.conf file, and here we will describe how you can configure shark, by briefly explaining the meaning of entries in standard Shark.conf file coming with shark distribution:
You can set the name of shark instance by editing enginename property. Here is a part of configuration file for setting this property:
######################### NAME # the name of shark instance - if shark is used in several VMs, this property # MUST be different for each of them enginename=Shark
If shark is being used from several virtual machines with the same DB, each Shark instance MUST have this property set differently. This is important because of process locking - when a process is used by one thread, it shouldn't be used by other thread at the same time, even if this other thread is in different VM. The process locking is based on the name of shark instance, and the Id of process.
You can set the way how the standard shark kernel will react when the process has nowhere to go after an activity is finished, and all activity's outgoing transitions are unsatisfied (evaluated to false). Of course, this parameter has meaning only for the activities that have at least one outgoing transition.
Here is a part of configuration file for setting this property:
######################### KERNEL SETTING for UNSATISFIED SPLIT CONDITIONS # There can be a cases when some activity that has outgoing transitions other # then to itself (other then circular one), has nowhere to go based on # calculation of these conditions (all of the conditions are evaluated to false) # In that case, the process could hang (it will not go anywhere, and it will # also not finish), finish (if there is no other active activities), or # the last transaction that finishes the activity will be rolled back. # This settings apply to the block activity's activities also, but the difference # is that if you set parameter to FINISH_IF_POSSIBLE, shark will actually # finish block activity if possible. # The possible values for the entry are IGNORE, FINISH_IF_POSSIBLE and ROLLBACK, # and default kernel behaviour is FINISH_IF_POSSIBLE #SharkKernel.UnsatisfiedSplitConditionsHandling=FINISH_IF_POSSIBLE
So, there are three possible solutions as described, and the default one is to finish the process if possible.
XPDL spec does not say that OTHERWISE transition should be executed only if no other transition condition is evaluated to true (in the case of XOR split). So, if you i.e. put OTHERWISE transition to be the first outgoing transition of some activity, other transition's condition won't be even considered.
You can configure shark to deviate from the spec, so that OTHERWISE transition is evaluated and executed only if no other transition condition is evaluated to true. To do that, you should set the following property to true.
SharkKernel.handleOtherwiseTransitionLast=false
This parameter could be saving lot of headaches to XPDL designers, by removing the extra care on OTHERWISE transition positioning.
Determines if kernel will create assignments - default is true. There are situations when assignment creation is not necessary, and this is the case when you always execute activities directly using change_state() WfActivity method.
SharkKernel.createAssignments=true
Since this setting affects the complete engine, you should carefully consider if application you're accessing shark with allows you to change the default setting.
It is possible to force kernel to re-evaluate assignments during shark initialization. This can be done by changing the following property:
#Assignments.InitialReevaluation=false
If you set this property to true, all not-accepted assignments are going to be re-evaluated (old ones will be deleted, and new ones will be created based on current mappings, current state of User/Group information and current implementation of AssignmentManager class).
Default kernel setting is not to re-evaluate assignments.
Determines if kernel will delete other assignments from DB everytime when someone accepts/rejects assignment, and will re-evaluate assignments each time this happens. If it is set to true, the side-effect is that if there was reassignment, and the user that got this reassigned assignment rejects it, he will not get it afterwards.
SharkKernel.deleteOtherAssignments=true
The shark kernel default is true.
If you want shark to fill its Process and Resource caches at startup, you should edit the following entries from configuration file:
#Cache.InitProcessCacheString=* #Cache.InitResourceCacheString=*
If you uncomment these lines, all processes and resources will be created based on DB data, and will be filled into cache (actually, this number is restricted by the cache size).
The value of these properties can be set as a comma separated list of the process/resource ids that need to be put into cache on engine start, e.g.: Cache.InitProcessCacheString=1_test_js_basic, 5_test_js_Game
Shark kernel default is not to initialize caches.
If you want shark not to reevaluate deadlines each time external deadline management checks for deadlines, you should set following entry to false (default kernel setting is true)
#Deadlines.reevaluateDeadlines=true
Determines if process or activity context will be used when re-evaluating deadlines Default kernel setting is activity context.
Deadlines.useProcessContext=false
Determines if asynchronous deadline should be raised only once, or every time when deadline check is performed. Default kernel setting is true (to raise deadline only once).
Deadlines.raiseAsyncDeadlineOnlyOnce=true
Determines if kernel will create a lock for process created during execution of subflow activities. In the case when you implement tool agent that opens its own thread, and communicates with shark, there are cases (when there is an automatic subflow process defined in XPDL) locking is required.
SharkKernel.lockSubProcesses=false
Default kernel setting is false.
Determines if old event audit data should be persisted or not. Default is to persist. The value of this property must be respected by both, the kernel, and event audit manager.
PERSIST_OLD_EVENT_AUDIT_DATA=true
Default kernel setting is true.
You can set the location of repository used by shark find XPDLs that can be loaded into shark's memory by changing the following part of configuration file:
######################## EXTERNAL REPOSITORY FOLDER SETTING # Shark currently uses File system repository for holding XPDL definitions, and # this is where you can specify location of this repository. # If you want to specify it by relative path, you must know that this path must # be relative to the Shark.conf file (in conf folder) EXTERNAL_PACKAGES_REPOSITORY=repository/external
WARNING: under Unix OS, the application needs to have a permission to write in this folder.
By setting this entry you are determining what would be the location of shark's repository.
External repository can be managed by the client admin application, XPDL files (packages) can be added or removed from this repository. Only XPDL files that are placed into this repository can be loaded into engine, and used to instantiate processes based on definitions contained within these files
If you are using a LDAP server to hold your organization structure, you can configure shark to use our LDAP implementation of UserGroup and Authentication interface (it will be explained later in the text how to set it up), and then you MUST define some LDAP properties.
At the moment, shark implementations of UserGroup and Authentication interfaces support two types of LDAP structures. The first structure is marked as type 0, and the second is marked as type 1. The LDAP structures are detailly explained in the document LDAP structures in Shark (html, pdf)
You can set this properties based on your LDAP server configuration, by changing the following part of configuration file:
######################### LDAP SETTINGS # Shark can use LDAP implementation of Authentication and UserGroup interfaces, # and these are settings required by these implementations to access and # browse the LDAP server LDAPHost=localhost LDAPPort=389 # possible values for LDAPStructureType parameter are 0 and 1 # 0 is simple structure, the possibility that one group or user belongs to more # than one group is not supported # 1 is more complex structure that supports the possibility that one group or # user belongs to more than one group is not supported LDAPStructureType=1 LDAPSearchBase= LDAPGroupObjectClasses=organizationalUnit LDAPUserObjectClasses=inetOrgPerson # parameter LDAPRelationObjectClasses is only needed for LDAPStructureType=1 LDAPRelationObjectClasses=groupOfNames LDAPGroupUniqueAttributeName=ou LDAPGroupDescriptionAttributeName=description LDAPUserUniqueAttributeName=userid # parameter LDAPRelationUniqueAttributeName is only needed for LDAPStructureType=1 LDAPRelationUniqueAttributeName=cn # parameter LDAPRelationMemberAttributeName is only needed for LDAPStructureType=1 LDAPRelationMemberAttributeName=member LDAPUserPasswordAttributeName=userpassword LDAPUserRealNameAttributeName=cn LDAPUserFirstNameAttributeName=givenName LDAPUserLastNameAttributeName=sn LDAPUserEmailAttributeName=mail LDAPUser=sasaboy LDAPPassword=s # parameter LDAPGroupGroupsName is only needed for LDAPStructureType=1 LDAPGroupGroupsName=Groups # parameter LDAPGroupUsersName is only needed for LDAPStructureType=1 LDAPGroupUsersName=Users # parameter LDAPGroupGroupRelationsName is only needed for LDAPStructureType=1 LDAPGroupGroupRelationsName=GroupRelations # parameter LDAPGroupUserRelationsName is only needed for LDAPStructureType=1 LDAPGroupUserRelationsName=UserRelations
LDAPHost - the address of the machine where LDAP server is running
LDAPPort - the port through which LDAP server can be accessed
LDAPStructureType - if set to 0, the simple structure is used in which the possibility that one group or user belongs to more than one group is not supported, if set to 1, the more complex structure is used which supports the possibility that one group or user belongs to more than one group is not supported
LDAPSearchBase - the name of the context or object to search (this is the root LDAP node where all queries will start at).
LDAPGroupObjectClasses - the comma separated list of LDAP object classes representing Group of users. It is important that these classes must have a mandatory attribute whose value uniquely identifies each entry throughout the LDAP tree.
LDAPUserObjectClasses - the comma separated list of LDAP object classes representing shark users. It is important that these classes must have a mandatory attribute whose value uniquely identifies each entry throughout the LDAP tree.
LDAPRelationObjectClasses - only used in structure type 1, the comma separated list of LDAP object classes representing relations between shark users and group or between shark groups. It is important that these classes must have a mandatory attribute whose value uniquely identifies each entry throughout the LDAP tree.
LDAPGroupUniqueAttributeName - the name of attribute that is mandatory for each LDAP object class representing Group of users. The value of this attribute MUST be unique for each LDAP entry for these object classes throught the LDAP tree.
LDAPGroupDescriptionAttributeName - the name of attribute of LDAP object classes representing Group of users that represents the Group description.
LDAPUserUniqueAttributeName - the name of attribute that is mandatory for each LDAP object class representing User. The value of this attribute MUST be unique for each LDAP entry for these object classes throughout the LDAP tree. When shark uses LDAP for authentication and user group management, this attribute represents the username for logging into shark.
LDAPRelationUniqueAttributeName - only used in structure type 1, the name of attribute that is mandatory for each LDAP object class representing Relation of groups or group and users. The value of this attribute MUST be unique for each LDAP entry for these object classes throught the LDAP tree
LDAPRelationMemberAttributeName - only used in structure type 1,the name of attribute of LDAP object classes (representing Relation of groups or group and users) that represents member that is included (user or group) in the relation.
LDAPPasswordAttributeName - the name of attribute that is mandatory for each LDAP object class representing User. When shark uses LDAP for authentication and user group management, this attribute represents the password needed for logging into shark.
LDAPUserRealNameAttributeName - the name of the attribute of LDAP object classes representing User, that represents the real name of the shark user.
LDAPUserFirstNameAttributeName - the name of the attribute of LDAP object classes representing User, that represents the first name of the shark user.
LDAPUserLastNameAttributeName - the name of the attribute of LDAP object classes representing User, that represents the last name of the shark user.
LDAPUserEmailAttributeName - the name of the attribute of LDAP object classes representing User, that represents user's email address.
LDAPUser - when LDAP server requires credentials for reading, this is the username that will be used when connecting LDAP server
LDAPPassword - when LDAP server requires credentials for reading, this is the password that will be used when connecting LDAP server
LDAPGroupGroupsName - only used in structure type 1, the name of the specific group that must be created and which will contain all groups
LDAPGroupUsersName - only used in structure type 1, the name of the specific group that must be created and which will contain all users
LDAPGroupGroupRelationsName - only used in structure type 1, the name of the specific group that must be created and which will contain all relations between groups
LDAPGroupUserRelationsName - only used in structure type 1, the name of the specific group that must be created and which will contain all relations between groups and users
If one wants to give its own implementation of CallbackUtilities interface, he can do it by changing the following attribute:
######################### CALLBACK UTILITIES # used for logging, and getting the shark properties # the default kernel setting is as follows #CallbackUtilitiesClassName=org.enhydra.shark.CallbackUtil
The name of the class that is used by default is commented.
This interface implementation is passed to all internal interface implementations, and is used by those implementations to read shark property values, and to log events.
If one wants to replace some parts of kernel with its own implementation (i.e. to replace WfActivityInternal, WfProcessInternal, ... implementations), he should create its own class based on this interface, and configure shark to use it.
This can be done by changing the following part of configuration file:
######################### OBJECT FACTORY # the class name of the factory used to creating kernel objects # the default kernel setting is as follows #ObjectFactoryClassName=org.enhydra.shark.SharkObjectFactory
The name of the class that is used by default is commented.
If one wants to set its own ToolAgentManager implementation, that will communicate with tool agents in a different way than the standard implementation does, he can configure the following:
######################### TOOL AGENT MANAGER # the class name of the manager used to execute tool agents # the default kernel setting is as follows #ToolAgentManagerClassName=org.enhydra.shark.ToolAgentManagerImpl
The name of the class that is used by default is commented.
E.g., by giving your own implementation of this class, along with giving new implementation of WfActivityInternal interface, and ObjectFactory that would generate this new implementation of WfActivityInternal interface, it is possible to configure shark to work as a Threaded engine, and to open new threads for each Tool type activity.
ExpressionBuilderManager is newly introduced component in Shark architecture. Its functionality simply didn't fit into any of previously existing. Expression builders provide an hierarchy of interfaces to ease the building of expressions for Wf*Iterators.
ExpressionBuilderManagerClassName=org.enhydra.shark.ExpressionBuilderMgr
Default setting provides DODS compatible implementation.
Wf-XML interoperability (WfMC interface 4) has introduced yet another component into Shark. This component main role is to provide connectivity to other engines through Wf-XML.
If you don't intend to deploy Shark as Wf-XML service, you may leave this commented out, but if you want to make your deployment of the Shark engine to communicate with others (engines from other vendors), first setting is mandatory. Other two are to help this component to choose which IP address or name and port it should listen to.
WfEngineInteroperabilityManagerClassName=org.enhydra.shark.interoperability.WfXMLInteroperabilityImpl Interoperability.Host=localhost Interoperability.Port=8080
Note
Shark comes with Axis based service, but since we didn't want to pack complete server, Shark uses SimpleAxisServer whose API doc clearly says: “This is a simple implementation of an HTTP server for processing SOAP requests via Apache's xml-axis. This is not intended for production use. Its intended uses are for demos, debugging, and performance profiling.”This section of configuration file is related to DODS implementation of persisting APIs.
In shark distribution, we provide SQL scripts for creating tables for the most DBs supported by DODS, and appropriate LoaderJob files that can be used by Octopus to create DB tables if providing appropriate drivers. This files can be found in conf/sql folder.
The default database used is HypersonicSQL, and settings for other DBs are commented, and this is the part of configuration file that shows this:
# # The jdbc driver to use, and Database url. DatabaseManager.DB.sharkdb.JdbcDriver="org.hsqldb.jdbcDriver" DatabaseManager.DB.sharkdb.Connection.Url="jdbc:hsqldb:C:/users/sasaboy/sdb/Shark/output/Shark/db/hsql/hsql" DatabaseManager.DB.sharkdb.ObjectId.NextWithPrefix = true DatabaseManager.DB.sharkdb.Connection.ShutDownString = SHUTDOWN # DB2 #DatabaseManager.DB.sharkdb.JdbcDriver="COM.ibm.db2.jdbc.app.DB2Driver" #DatabaseManager.DB.sharkdb.Connection.Url="jdbc:db2:shark" # HypersonicSQL #DatabaseManager.DB.sharkdb.JdbcDriver="org.hsqldb.jdbcDriver" #DatabaseManager.DB.sharkdb.Connection.Url="jdbc:hsqldb:C:/users/sasaboy/Shark/output/Shark/db/hsql/hsql" # Informix #DatabaseManager.DB.sharkdb.JdbcDriver="com.informix.jdbc.IfxDriver" #DatabaseManager.DB.sharkdb.Connection.Url="jdbc:informix-sqli://localhost/shark" # MSQL #DatabaseManager.DB.sharkdb.JdbcDriver="com.microsoft.jdbc.sqlserver.SQLServerDriver" #DatabaseManager.DB.sharkdb.Connection.Url="jdbc:microsoft:sqlserver://localhost:1433;DatabaseName=shark;SelectMethod=cursor" # MySQL #DatabaseManager.DB.sharkdb.JdbcDriver="org.gjt.mm.mysql.Driver" #DatabaseManager.DB.sharkdb.Connection.Url="jdbc:mysql://localhost/shark" # Oracle #DatabaseManager.DB.sharkdb.JdbcDriver="oracle.jdbc.driver.OracleDriver" #DatabaseManager.DB.sharkdb.Connection.Url="jdbc:oracle:thin:@localhost:1521:shark" # PostgreSQL #DatabaseManager.DB.sharkdb.JdbcDriver="org.postgresql.Driver" #DatabaseManager.DB.sharkdb.Connection.Url="jdbc:postgresql://localhost/shark" #DatabaseManager.ObjectIdColumnName=ObjectId #DatabaseManager.VersionColumnName=ObjectVersion # Sybase #DatabaseManager.DB.sharkdb.JdbcDriver="com.ddtek.jdbc.sybase.SybaseDriver" #DatabaseManager.DB.sharkdb.Connection.Url="jdbc:sybase://localhost/shark"
To really be able to use appropriate DB, you also need to set the username and password, and this is done by changing the following part of configuration file:
# # Database user name. All connection are allocated by this user. # DatabaseManager.DB.sharkdb.Connection.User="sa" # Database user password. # DatabaseManager.DB.sharkdb.Connection.Password=""
To configure shark to use another DB, you should simply comment HypersonicSQL settings, and uncomment and edit settings for the DB you like, and to change username and password entries (this can be also done automatically by editing configure.properties file in the project root, and calling configure script).
There is another important DODS configuration aspect - the cache sizes:
# # Default cache configuration # DatabaseManager.defaults.cache.maxCacheSize=100 DatabaseManager.defaults.cache.maxSimpleCacheSize=50 DatabaseManager.defaults.cache.maxComplexCacheSize=25
If you know that several instances of shark will be used in several VMs, using the same DB, you should set all this cache sizes to zero. Along with this, cache manager implementation (explained later in the text) should not be used.
Following options are described together, although they affect different components, because option's intention and the effect produced are the same.
Determines the maximum size of String that will be stored in VARCHAR field. String which size is greater than specified value will be stored as a BLOB. The maximumum size that can be set is 4000 (the default one)
DODSPersistentManager.maxVARCHARSize=4000 DODSEventAuditManager.maxVARCHARSize=4000
Determines which data model will be used for storing process and activity variables. There are two options:
using standard data model, where all data types are in one table (including BLOB data type for persisting custom Java objects and large Strings
using optional data model, where one table contains all data types except BLOB, and there is another table that references previous table, and is used only for storing BLOB information (for persisting custom Java objects and large Strings)
Default is to use standard data model, but using optional data model can improve performance in use cases where there are not so many custom Java objects and large String objects, and when shark and DODS caches are not used, and this is especially better choice if using Oracle DB.
DODSPersistentManager.useStandardVariableDataModel=true DODSEventAuditManager.useStandardVariableDataModel=true
This API is used to store mapping information between XPDL applications and tool agent applications. Shark comes with DODS based application map persistence implementation.
You can provide your own implementation of application map persistence API, and replace the current implementation. The default implementation is DODS implementation.
#============================================================================= # Default application map persistence manager is DODS # #----------------------------------------------------------------------------- # # DODS application map persistent manager defaults # ApplicationMapPersistenceManagerClassName=org.enhydra.shark.appmappersistence.DODSApplicationMappingMgr # If set to true, the debug information on application mapping transaction will be # written to console #DODSApplicationMappingMgr.debug=false
NOTE: if you comment the lines above, shark will work without application map persistence API implementation.
If one would like to create its own Assignment manager, which would decide which assignments are to be created for an activity, he can implement its own Assignment manager, based on AssignmentManager interface, and configure shark to use it by changing the following setting:
AssignmentManagerClassName=org.enhydra.shark.assignment.StandardAssignmentManager
Shark comes with three different implementations of this manager:
Standard - just returns the list of users passed as a parameter, or if there are no users in the list, it returns the user that created corresponding process.
History Related - if there are some special "Extended attributes" defined in XPDL for some activity definition, this implementation checks the assignment history (who has already executed activity with such definition, ...) to make a decission about assignments that should be created.
XPDL Straight Participant Mapping - it makes assignments for the user that has the same Id as XPDL performer of activity.
NOTE: if you do not set any implementation (you simply comment line above), shark will use the default procedure. Actually, standard implementation of assignment API is not very useful, it basically just returns the first valid options.
Shark comes with two implementations of Authentication and UserGroup API. The first one is DB based (uses DB for storing and retrieving information about organizational structure), and the other one is LDAP based (uses LDAP server for getting organizational information).
Here is a part of configuration file for setting Authentication manager implementation:
#============================================================================= # Default AuthenticationManager is DODS # # WARNING: This and user/group manager must comply. #----------------------------------------------------------------------------- # #AuthenticationManagerClassName=org.enhydra.shark.authentication.LDAPAuthenticationManager AuthenticationManagerClassName=org.enhydra.shark.authentication.DODSAuthenticationManager # Specifies the size of LRU cache for holding user attributes (for shark performance reason) # for LRU implementation LDAPClient.userAttributesCacheSize=100 # Specifies the size of LRU cache for holding group attributes (for shark performance reason) # for LRU implementation LDAPClient.groupAttributesCacheSize=100 # The database used for Authentication when using DODS implementation #DODSAuthenticationManager.DatabaseName=sharkdb
It is IMPORTANT to mention that if you use LDAP implementation of Authentication API, you MUST use LDAP implementation of UserGroup API (the same story is for DODS implementations).
By default, shark uses DB based DODS implementation, and to switch to LDAP implementation, you should simply comment the line that refers to DODS, and uncomment one referring to LDAP (and do the same for UserGroup settings), and also to edit appropriate LDAP settings previously described.
NOTE: if you do not set any implementation (you simply comment line above), shark will not perform any authentication.
Shark comes with LRU based cache implementation for holding Process and Resource objects. By default, shark is configured to use this cache implementation, which can speed-up its use by the clients.
This is the section of configuration file that defines cache implementation, and its sizes:
#============================================================================= # Default cache is LRU # #----------------------------------------------------------------------------- # Cache defaults # CacheManagerClassName=org.enhydra.shark.caching.LRUCacheMgr # Default LRU cache sizes (LRU implementation default is 100 for each cache) #LRUProcessCache.Size=100 #LRUResourceCache.Size=100
NOTE: if you do not set any implementation (you simply comment line above), shark will not perform any caching.
The implementation of this API is used to store information about shark's processes, activities, ... into DB. Shark comes with DODS based instance persistence implementation. One can write its own implementation of this interface (maybe using Hibernate or EJB), and to configure shark to work with this implementation, he needs to edit the following section of configuration file:
# # DODS instance persistent manager defaults # InstancePersistenceManagerClassName=org.enhydra.shark.instancepersistence.DODSPersistentManager
Shark can't work without instance persistence implementation.
NOTE: If one would like to implement other instance persistence implementation, he should also give its own implementation of SharkTransaction API.
By default, DODS implementation of instance persistence interface does not delete finished processes, but they are left in DB. This behaviour can be changed by setting the following parameter to true:
# Determines if finished processes should be deleted from DB (DODS persistence # manager default is false) #DODSPersistentManager.deleteFinishedProcesses=false
Shark comes with two different implementation of this API. These implementations by default just log to the console if an activity/process exceeds its limit set by XPDL. For the standard implementation, the check of limits through this API must be started by the client, and for the timer based implementation (which shouldn't be used if you want shark to behave as a library because this implementation starts its own threads) this shouldn't be done.
If you would like to use your own implementation, you can edit the following line from shark's configuration file:
LimitAgentManagerClassName=org.enhydra.shark.limitagent.StandardLimitAgentManager
The lock master is used for synchronizing the processes - when using lock master, there can not be more then one thread working on the same process at the same time.
Shark comes with two implementations of the lock master interface, the "simple" one is used when you know that shark will be used only from one VM, and "DODS" implementation should be used when you know that shark will be used from several VMs accessing the same DB.
Default setting for lock master is "DODS", and it can be changed by commenting the line that corresponds to DODS lock master, and uncommenting the line that corresponds to simple lock master. Here is a part of shark's configuration file that determines usage of lock masters:
#============================================================================= # Default LockMaster is DODS # #----------------------------------------------------------------------------- # SimpleLockMaster defaults # #LockMasterClassName=org.enhydra.shark.processlocking.SimpleLockMaster # The number of milliseconds to wait for a locked process, -1 is default # for the simple lock master implementation, and it means wait forever #SimpleLockMaster.Timeout=-1 # The number of milliseconds to try to acquire lock for the process if we # must wait for it to be unlocked. Lock master will try to acquire process lock # every SimpleLockMaster.LockWaitTime milliseconds until it succeeds, or # until SimpleLockMaster.Timeout milliseconds has passed (int that case, an # exception will be thrown). # The simple lock master implementation default is 100 milliseconds #SimpleLockMaster.LockWaitTime=100 #----------------------------------------------------------------------------- # DODSLockMaster defaults # LockMasterClassName=org.enhydra.shark.processlocking.DODSLockMaster # The number of milliseconds to wait for a locked process, -1 is default # for the DODS lock master implementation, and it means wait forever DODSLockMaster.Timeout=1200 # The number of milliseconds to try to acquire lock for the process if we # must wait for it to be unlocked. Lock master will try to acquire process lock # every DODSLockMaster.LockWaitTime milliseconds until it succeeds, or # until DODSLockMaster.Timeout milliseconds has passed (int that case, an # exception will be thrown). # The DODS lock master implementation default is 100 milliseconds DODSLockMaster.LockWaitTime=400 # The database holding information on locked processes #DODSLockMaster.DatabaseName=sharkdb # The cache sizes must be set to zero DatabaseManager.DB.sharkdb.LockTable.cache.maxCacheSize=0 DatabaseManager.DB.sharkdb.LockTable.cache.maxSimpleCacheSize=0 DatabaseManager.DB.sharkdb.LockTable.cache.maxComplexCacheSize=0
As you can see, there are also some additional parameters for configuring the lock master (Timeout and LockWaitTime), which are pretty well described above.
When using DODS implementation of lock master, it is also important to set DODS cache sizes for LockTable to zero.
NOTE: you can work without implementation of Lock master (just comment the lines above), but then you must be certain that shark is used only from one VM, and only in one client Thread at a time.
Shark comes with a default logger implementation, implemented by the use of log4j. You can write your own implementation of Logging API, and set it by editing configuration file, and probably adding some additional entries in configuration file that will be read by your logger implementation. Here is a complete logger configuration for shark standard logger:
#
# Standard logging manager defaults
#
LoggingManagerClassName=org.enhydra.shark.logging.StandardLoggingManager
# Standard Logging manager is using log4j, and here is log4j configuration
#
# log4j.rootLogger=info, SharkExecution, Console
log4j.appender.Database=org.apache.log4j.RollingFileAppender
log4j.appender.Database.File=C:/users/sasaboy/Shark/output/Shark/logs/SharkPersistence.log
log4j.appender.Database.MaxFileSize=10MB
log4j.appender.Database.MaxBackupIndex=2
log4j.appender.Database.layout=org.apache.log4j.PatternLayout
log4j.appender.Database.layout.ConversionPattern=%d{ISO8601}: %m%n
log4j.appender.XMLOutFormatForPersistence=org.apache.log4j.FileAppender
log4j.appender.XMLOutFormatForPersistence.File=C:/users/sasaboy/Shark/output/Shark/logs/chainsaw-persistence.log
log4j.appender.XMLOutFormatForPersistence.append=false
log4j.appender.XMLOutFormatForPersistence.layout=org.apache.log4j.xml.XMLLayout
log4j.appender.PackageEvents=org.apache.log4j.RollingFileAppender
log4j.appender.PackageEvents.File=C:/users/sasaboy/Shark/output/Shark/logs/SharkPackageHandlingEvents.log
log4j.appender.PackageEvents.MaxFileSize=10MB
log4j.appender.PackageEvents.MaxBackupIndex=2
log4j.appender.PackageEvents.layout=org.apache.log4j.PatternLayout
log4j.appender.PackageEvents.layout.ConversionPattern=%d{ISO8601}: %m%n
log4j.appender.XMLOutFormatForPackageEvents=org.apache.log4j.FileAppender
log4j.appender.XMLOutFormatForPackageEvents.File=C:/users/sasaboy/Shark/output/Shark/logs/chainsaw-packageevents.log
log4j.appender.XMLOutFormatForPackageEvents.append=false
log4j.appender.XMLOutFormatForPackageEvents.layout=org.apache.log4j.xml.XMLLayout
log4j.appender.SharkExecution=org.apache.log4j.RollingFileAppender
log4j.appender.SharkExecution.File=C:/users/sasaboy/Shark/output/Shark/logs/SharkExecutionFlow.log
log4j.appender.SharkExecution.MaxFileSize=10MB
log4j.appender.SharkExecution.MaxBackupIndex=2
log4j.appender.SharkExecution.layout=org.apache.log4j.PatternLayout
log4j.appender.SharkExecution.layout.ConversionPattern=%d{ISO8601}: %m%n
log4j.appender.XMLOutFormatForExecution=org.apache.log4j.FileAppender
log4j.appender.XMLOutFormatForExecution.File=C:/users/sasaboy/Shark/output/Shark/logs/chainsaw-execution.log
log4j.appender.XMLOutFormatForExecution.append=false
log4j.appender.XMLOutFormatForExecution.layout=org.apache.log4j.xml.XMLLayout
log4j.appender.NTEventLog=org.apache.log4j.nt.NTEventLogAppender
log4j.appender.NTEventLog.source=SharkCORBA-Service
log4j.appender.NTEventLog.append=false
log4j.appender.NTEventLog.layout=org.apache.log4j.PatternLayout
log4j.appender.NTEventLog.layout.ConversionPattern="%d{ISO8601}: [%t], %p, %c: %m%n"
log4j.appender.Console=org.apache.log4j.ConsoleAppender
log4j.appender.Console.layout=org.apache.log4j.PatternLayout
log4j.appender.Console.layout.ConversionPattern=%d{ISO8601}: %m%n
log4j.logger.Persistence=INFO,Database
#log4j.logger.Persistence=INFO,Database,XMLOutFormatForPersistence
log4j.logger.PackageEventLogger=INFO,PackageEvents
#log4j.logger.PackageEventLogger=INFO,PackageEvents,XMLOutFormatForPackageEvents
log4j.logger.Shark=INFO,Console,SharkExecution
#log4j.logger.Shark=INFO,Console,SharkExecution,XMLOutFormatForExecutionThe standard logger implementation is written in the way that it could log even if there are no log4j settings defined in configuration file (so the implementation can't configure log4j), but log4j is configured from client application using shark.
The following log outputs are generated by default:
Server execution flow log - logs every significant shark operation like package loading, process instantiation, activity completion, .... These logs are also displayed in the console during shark execution.
Package Handling Events - logs every operation performed with Package definition files (XPDL files). These operations are:
loading of the package from external repository into shark's memory
unloading of the package from the shark
updating of the package that is already in the shark's memory
Server persistence log - logs every operation related to communication among DODS instance persistence implementation, and underlying database.
You have the possibility to force Shark to make log files that can be viewed using log4j's chainsaw viewer. To do so, for each type of logger, you have to comment first and uncomment the second line that refers to the logger at the bottom of logger configuration.
Then, the output logs will be also generated into XML log files (chainsaw-execution.log, chainsaw-packageevents.log and chainsaw-persistence.log) that can be read by chainsaw.
The chainsaw can be started by using proper "chainsaw" script from the root of the project. When it is started, you have to open wanted log file by using its "File->Load file..." menu item, and it will present you the proper logs.
NOTE: If you do not want any logging, comment LoggingManagerClassName line above, and shark will not log anywhere.
This API is used to store mapping information between XPDL participants and shark users. Shark comes with DODS based participant map persistence implementation.
You can provide your own implementation of participant map persistence API, and replace the current implementation. The default implementation is DODS implementation.
#============================================================================= # Default participant map persistence manager is DODS # #----------------------------------------------------------------------------- # # DODS participant map persistent manager defaults # ParticipantMapPersistenceManagerClassName=org.enhydra.shark.partmappersistence.DODSParticipantMappingMgr # If set to true, the debug information on participant mapping transaction will be # written to console #DODSParticipantMappingMgr.debug=false
NOTE: if you comment the lines above, shark will work without participant map persistence API implementation.
This API is used to store information about XPDL definitions and versions. Shark comes with two implementations of this API: FileSystem based, and DODS based.
You can provide your own implementation of this API, and replace the current implementation. The default implementation is DODS implementation.
# Default repository persistent manager is DODS # #RepositoryPersistenceManagerClassName=org.enhydra.shark.repositorypersistence.FileSystemRepositoryPersistenceManager # The location of xpdl repository. # If you want to specify it by relative path, you must know that this path must # be relative to the Shark.conf file (in conf folder) FileSystemRepositoryPersistenceManager.XPDL_REPOSITORY=repository/internal # The location of xpdl history repository. # If you want to specify it by relative path, you must know that this path must # be relative to the Shark.conf file (in conf folder) FileSystemRepositoryPersistenceManager.XPDL_HISTORY_REPOSITORY=repository/internal/history RepositoryPersistenceManagerClassName=org.enhydra.shark.repositorypersistence.DODSRepositoryPersistenceManager # The database used for Repository persistence when using DODS implementaion #DODSRepositoryPersistenceManager.DatabaseName=sharkdb # If set to true, the debug information on repository transaction will be # written to console #DODSRepositoryPersistenceManager.debug=false
NOTE: Shark can't work without implementation of this API.
Shark comes with standard scripting manager implementation. This is a factory for returning appropriate script evaluator, and standard implementation offers three different script evaluators: Python, Java script and Bean shell.
#============================================================================= # Default Scripting manager is Standard # #----------------------------------------------------------------------------- # ScriptingManagerClassName=org.enhydra.shark.scripting.StandardScriptingManager
Shark can't work without Scripting API implementation.
This API is used to store mapping information for XPDL script language. Shark comes with DODS based script map persistence implementation.
You can provide your own implementation of script map persistence API, and replace the current implementation. Currently, this API is not defined, so there is no use of its implementation.
#============================================================================= # Default script map persistence manager is DODS # #----------------------------------------------------------------------------- # # DODS script map persistent manager defaults # #ScriptMapPersistenceManagerClassName=org.enhydra.shark.mappersistence.DODSScriptMappingMgr # If set to true, the debug information on script mapping transaction will be # written to console #DODSScriptMappingMgr.debug=false
NOTE: if the lines above are commented, shark will work without script map persistence API implementation.
This API is not well defined, and currently serves just like an example. In the future, this API will contain methods to authorize shark usage on the level of particular methods (i.e. to create, abort, terminate or suspend some process, user will have to be authorized).
#============================================================================= # Default Security manager is Standard # #----------------------------------------------------------------------------- # SecurityManagerClassName=org.enhydra.shark.security.StandardSecurityManager
NOTE: If you don't want any authorization, you just need to comment line above - shark can work without this API implementation.
Shark comes with standard ToolAgentFactory implementation, and with several example tool agents (JavaScript, BeanShell, RuntimeApplication, SOAP, Mail and JavaClass tool agent), and with default tool agent implementation.
To learn more about tool agent, you should look at ToolAgent documentation.
These are configuration settings for tool agents:
#============================================================================= # Default Tool agent settings # #----------------------------------------------------------------------------- # ToolAgentFactoryClassName=org.enhydra.shark.toolagent.ToolAgentFactoryImpl # The list of tool agents ToolAgent.JavaClassToolAgent=org.enhydra.shark.toolagent.JavaClassToolAgent ToolAgent.JavaScriptToolAgent=org.enhydra.shark.toolagent.JavaScriptToolAgent ToolAgent.BshToolAgent=org.enhydra.shark.toolagent.BshToolAgent ToolAgent.RuntimeApplicationToolAgent=org.enhydra.shark.toolagent.RuntimeApplicationToolAgent ToolAgent.MailToolAgent=org.enhydra.shark.toolagent.MailToolAgent ToolAgent.SOAPToolAgent=org.enhydra.shark.toolagent.SOAPToolAgent # Default tool agent is used when there is no mappings for some # XPDL application definition DefaultToolAgent=org.enhydra.shark.toolagent.DefaultToolAgent # Specifies the size of cache for holding ext. attributes (for shark performance reason) # Default -1 means unlimited #AbstractToolAgent.extAttribsCacheSize=-1
NOTE: shark can work without tool agent API implementation, but then it can only execute processes that do not contain any "Tool" activity.
Shark has default DODS implementation of this API, and this comply to the implementation of instance persistence API. It is used for creating SharkTransaction objects. SharkTransaction is visible to the client, and to the internal shark interfaces. Shark's client API has duplicate methods, one with and one without transaction. It is possible to use Shark within external transaction.
#============================================================================= # Default transaction factory is DODS # #----------------------------------------------------------------------------- # DODSTransactionFactory defaults # TransactionManagerClassName=org.enhydra.shark.transaction.DODSTransactionFactory # If set to true, the debug information on shark transaction will be # written to console #DODSTransactionFactory.debug=false
Shark comes with two implementations of Authentication and UserGroup API. The first one is DB based (uses DB for storing and retrieving information about organizational structure), and the other one is LDAP based (uses LDAP server for getting organizational information).
Here is a part of configuration file for setting UserGroup manager implementation:
#============================================================================= # Default UserGroupManager is DODS # # WARNING: This and authentication manager must comply. #----------------------------------------------------------------------------- #UserGroupManagerClassName=org.enhydra.shark.usergroup.LDAPUserGroupManager UserGroupManagerClassName=org.enhydra.shark.usergroup.DODSUserGroupManager # The database used for User/Group when using DODS implementaion #DODSUserGroupManager.DatabaseName=sharkdb
It is IMPORTANT to mention that if you use LDAP implementation of UserGroup API, you MUST use LDAP implementation of Authentication API (the same story is for DODS implementations).
By default, shark uses DB based DODS implementation, and to switch to LDAP implementation, you should simply comment the line that refers to DODS, and uncomment the one referring to LDAP (and do the same for Authentication settings), and also to edit appropriate LDAP settings previously described.
NOTE: shark can work without implementation of this API - if you do not want to use any implementation, simply comment line above.
Shark has default DODS implementation of this API, and this comply to the DODS implementation of UserGroup API. It is used for creating UserTransaction objects. UserTransaction is visible to the client, and to the internal shark interfaces (Authentication and UserGroup interfaces use it). Shark's client API has duplicate methods, one with and one without transaction. It is possible to use Shark within external transaction.
#============================================================================= # Default user transaction factory is DODS # #----------------------------------------------------------------------------- # DODSUserTransactionFactory defaults # UserTransactionManagerClassName=org.enhydra.shark.usertransaction.DODSUserTransactionFactory # If set to true, the debug information on user transaction will be # written to console #DODSUserTransactionFactory.debug=false
You can specify cache sizes for object Ids (activity and process Ids). When some process or activity is created, shark asks its data layer (default DODS layer) for unique Id. This Id generation is synchronized on DB, so that shark can be used from different VMs at a time. To tell shark not to go to the DB so often, you can specify an Id cache for objects:
#============================================================================= # DODS Settings for Id Generator #----------------------------------------------------------------------------- # default cache size for Ids (if cache size for particular object Id is not # specified, then this size is used, and if this cache size also isn't # specified, program default is used) DODS.defaults.IdGenerator.CacheSize=100 # cache size for process instance Ids #DODS.IdGenerator._process_.CacheSize=100 # cache size for activity instance Ids #DODS.IdGenerator._activity_.CacheSize=100
You can set some parameters that will be used by shark deployed as CORBA server.
################################# CORBA Settings when used as CORBA service nameserverhost=localhost nameserverport=10123 DEFAULT_ADMINISTRATOR_GROUP_NAME=AdminGroup DEFAULT_ADMINISTRATOR_GROUP_DESCRIPTION=Default Admin Group DEFAULT_ADMINISTRATOR_USERNAME=admin DEFAULT_ADMINISTRATOR_PASSWORD=enhydra DEFAULT_ADMINISTRATOR_FIRST_NAME=Administrator DEFAULT_ADMINISTRATOR_LAST_NAME=Admin DEFAULT_ADMINISTRATOR_EMAIL=admin@together.at nameserver.executable=C:/j2sdk1.4.2_04/bin/tnameserv # if set to value greater than zero, shark's CORBA wrapper will periodically # restart nameserver (the given period is in minutes) nameserver.restarting_period_minutes=0 Deadlines.SERVER_SIDE_CHECKING=false Limits.SERVER_SIDE_CHECKING=false # The time in millis used to poll shark for checking deadlines if # server side checking is ON Deadlines.pollingTime=300000 # The time in millis used to poll shark for checking limits if # server side checking is ON Limits.pollingTime=60000
By setting nameserverhost and nameserverport properties, you are specifying the nameserver machine and port (the name that will be used to register shark with nameserver is the one set by enginename property).
When clients want to connect to the Shark server, they need to contact the same nameserver, and ask for the shark server main object by using the name specified by 'enginename' property.
Parameters that begin with DEFAULT_ADMINISTRATOR determine default administrator user. If you leave this properties as they are, you will be able to log on shark CORBA server using "admin" as username, and "enhydra" as password.
You can specify if shark server will check for deadlines and limits by itself (by opening special threads which would periodically ask shark to check it). In that case, you can setup the polling times.
It has been noticed that CORBA server has memory leaking. This option tries to prevent it, by making the server track and disconnect objects when client says so (on SharkConnection and other intefaces disconnect method). When turned off, server behaves as before, not caring about object deallocation.
CORBAServer.TrackAndDisconnect=true
If set to true, when CORBA server has problem contacting external requester for the first time, due to the network problem or client application shutdown, next time it won't try to contact the requester for this process instance.
CORBAServer.ignoreProblematicRequester=true
You can find here DODS generated documentation of various data models used in default shark configuration:
Instance persistence data model - (html, pdf)
Event audit data model - (html, pdf)
Participant mapping persistence data model - (html, pdf)
Application mapping persistence data model - (html, pdf)
Repository persistence data model - (html, pdf)
User group data model - (html,pdf)
Process locking data model - (html, pdf)
Id Counter data model - (html,pdf)
When using DODS as implementation of persistence APIs, shark can work with different databases - practically, any database supported by DODS can be used.
Here is the list of DODS supported databases:
DB2
Informix
HypersonicSQL
MSQL
MySQL
Oracle
PostgreSQL
Sybase
The default database coming with Shark distribution is HypersonicSQL, and we also tested it with DB2, MSQL, MySQL, Oracle and PostgreSQL.
The scripts for creating tables for various databases (by using Octopus) are distributed with Shark. If you want to use different database then the one originally configured to work with Shark (HypersonicSQL database), you should do the following:
first you'll need to stop any Shark instance that may be running( POJO swing admin/worklist handler, or CORBA server).
Edit the configure.properties file and set values for:
- db_loader_job
name of the directory containing Octopus loader job, options are: db2, hsql, informix, msql, mysql, oracle, postgresql, sybase
- db_user
username for database authentication
- db_passwd
password for database authentication
- db_ext_dirs
directory containing jar file(s) with JDBC driver, if you need more then one directory specified here - use ${path.separator} to concatenate them
- ${db_loader_job}_JdbcDriver
classname of the JDBC driver you want to use
These entries are already filled with default values.
- ${db_loader_job}_Connection_Url
full database URL
These entries are already filled with default values, too.
run the configure.[bat|sh]
If everything goes well, when you start shark, it will use the database you've configured.
Note
When loading newly created database, Octopus will complain about not being able to drop indices and tables, but theses warnings should be ignored.