The Stardust API is organized along the concepts of specific services needed to perform common usage scenarios. While typical workflow usage will mainly involve worklist introspection followed by process and activity execution, administrative operations or reporting tasks usually need a completely different set of APIs.
This chapter comprises the following topics:
The initial entry point to the Stardust API is the interface org.eclipse.stardust.engine.api.runtime.ServiceFactory. Implementations of that interface allow you to centrally obtain (and optionally release) service references. One benefit is the transparent use of credentials for authentication and authorization needs. Another benefit is the option to be able to always write client code as if it would use the plain Java APIs as the service factory will transparently adapt EJB remote interfaces to the local API if needed, thus enabling easy transition from local deployments to distributed EJB or Web deployments.
Service factory implementations are obtained from service factory locators:
The service factory obtained from the appropriate locator will ensure proper bootstrapping of Stardust client code and install all necessary transparent treatment like EJB exception unwrapping or security context management.
While essential in plain Java environments, use of such service factories is
optional in container environments like EJB or Web. As in the case of a plain Java usage,
scenario service bootstrapping includes both client-side as well as implementation-side
requirements (i.e. credential passing as well as resource binding), usage of a service
factory is downright required. In managed environments the implementation-side setup is
well served by the container itself, thus reducing the need for such extra efforts.
Depending on your needs you may safely continue directly using Stardust Session Bean homes
looked up via JNDI.
You will use the appropriate service factory to authenticate and establish a connection with the Stardust runtime environment. Assuming you authenticate and establish a connection with the Stardust runtime, you can get a reference to Stardust services via this initialized service factory. You can initialize the service factory in the following way:
ServiceFactory sf = ServiceFactoryLocator.get(user, pwd, properties);
Note
The ServiceFactory caches the authenticated Stardust services for the
user. For use in a production environment it is important that you cache the
ServiceFactory per user. Not caching the ServiceFactory means that a new login
will be performed for every interaction with the engine.
When using the ServiceFactoryLocator you have the option to pass one or more additional properties besides the user's name and password like the user's realm, partition and domain. Please refer to the Managing Multi Partition Stardust Installations chapter of the Administrative Concepts part to receive more information on this credentials. The following keys in the properties map will be filled with the values passed as parameters, the following parameters are used:
SecurityProperties.REALM,SecurityProperties.PARTITION andSecurityProperties.DOMAIN.In case partition, domain and realm are provided as credentials like user or password, the following keys in the properties map will be filled with the values passed as parameters:
SecurityProperties.CRED_REALM,SecurityProperties.CRED_PARTITION andSecurityProperties.CRED_DOMAIN.If these parameters are empty, the default values residing in the carnot.properties
file are used, if existing:
Security.DefaultRealm, if SecurityProperties.REALM is
empty.Security.DefaultPartition, if SecurityProperties.PARTITION
is empty.Security.DefaultDomain, if SecurityProperties.DOMAIN
is empty. In case it does not exist, the partition's ID is used. (There must be one
partition with the same ID as the domain).If no Security.DefaultRealm, Security.DefaultPartition or Security.DefaultDomain
are set in the carnot.properties file, the following default values will be used:
The following code snippet shows how to fill the properties map:
import org.eclipse.stardust.engine.api.runtime.ServiceFactory;
import org.eclipse.stardust.engine.api.runtime.ServiceFactoryLocator;
public ServiceFactory getTestService()
{
Map properties = new HashMap();
properties.put(SecurityProperties.PARTITION, partition);
properties.put(SecurityProperties.DOMAIN, domain);
properties.put(SecurityProperties.REALM, realm);
return ServiceFactoryLocator.get(user, password, properties);
}
To provide the login screens for users with additional input fields to login with
their partition, domain and realm, the
following properties residing in the carnot.properties file have to be set to true
respectively:
Security.PromptRealmSecurity.PromptPartitionSecurity.PromptDomainFor more information about security properties residing in the carnot.properties
file, please refer to the Security
section of the Client
Side Properties chapter.
The
org.eclipse.stardust.engine.core.runtime.beans.EmbeddedServiceFactory
class determines, whether an execution takes
place in the engine context
and returns an instance of the EmbeddedServiceFactory.
To return the EmbeddedServiceFactory in case of Stardust Portal internal
invocation and only start authenticating if the call is remote,
pass a transaction constant to indicate the intent of working in the scope
of the current transaction. The transaction constants
provided by the EmbeddedServiceFactory are:
CURRENT_TX - returns ServiceFactory that works
within the same transaction without creating a new property layerCURRENT_TX_WITH_AUTO_FLUSH - returns ServiceFactory
that works within the same transaction without creating a new property layer
and automatically flushes the changes at the end of the service call.CURRENT_TX_WITH_PROPERTY_LAYER - returns ServiceFactory
that works within the same transaction with an added property layerE.g. use:
ServiceFactory sf = ServiceFactoryLocator.get(CredentialProvider.CURRENT_TX);
You can determine for which user IDs (accounts) and user OIDs
session tracking is disabled. Set a comma separated list of these users in the
property Carnot.AuditTrail.Session.NoSessionTracking in your carnot.properties
file. To disable session tracking for all users use *.
To determine the interval after a session is defined
as expired, add a value in minutes to the property
Carnot.AuditTrail.Session.ExpirationInterval
in your carnot.properties file.
The default value is 60 minutes.
You can determine a delay until cached changes on
user session entries are added to the database.
Set this value in seconds via the property Carnot.AuditTrail.Session.UserActivityUpdateDelay in
your carnot.properties file. The default value is 10 seconds.
Stardust provides the following services:
For detailed information on the methods of these services, please refer to the according JavaDoc.
The WorkflowService provides all functionality for workflow enactment for a Stardust runtime environment such as:
The following classes are provided for this service:
In case of an EJB deployment the RemoteWorkflowService bean is designed to be deployed as a stateless Session Bean.
The QueryService provides functionalities for introspecting a Stardust runtime environment such as:
The following classes are provided for this service:
In case of an EJB deployment the RemoteQueryService bean is designed to be deployed as a stateless Session Bean.
The AdministrationService provides special functionalities to administer a Stardust runtime environment such as:
The following classes are provided for this service:
Use of the administration service requires the user to be granted the predefined role Administrator.
In case of an EJB deployment the RemoteAdministrationService bean is designed to be deployed as a stateless Session Bean.
The UserService provides user management functionalities needed in case of deployments using the Stardust integrated security such as:
In case of deployments using third-party security infrastructure such user and user group management functions usually have to be performed using tools of the external system. In such a scenario it might even make sense to omit deployment of the user service at all.
The following classes are provided for this service:
In case of an EJB deployment the RemoteUserService bean is designed to be deployed as a stateless Session Bean.
The DocumentManagementService provides all functionality for Document Management operations in an Stardust runtime environment. This includes the following:
The following classes are provided for this service:
In case of an EJB deployment the DocumentManagementService bean is designed to be deployed as a stateless Session Bean.
Stardust provides a service command interface
ServiceCommand as a client side wrapper around a series of service
invocations that have to be performed in a single server side transaction. The
execute method serves to execute the service command:
Serializable execute(ServiceFactory sf);
The parameter is a
ServiceFactory provided by the engine that will ensure that all service calls
will be performed in the parent transaction. The method returns
the result of the service call execution, which will be returned to the client.
For example, WorkflowService.execute(ServiceCommand) returns the
Serializable object produced by the execution of the ServiceCommand.
Use the ServiceCommand in the following way:
ServiceFactory defining a call sequence definition.ServiceCommand with this ServiceFactory to the server.ServiceCommand in
one transaction and stores the return values as defined.ServiceCommand.ServiceCommand.A generic interface
Configurable exists for objects that supports client-side configuration.
It allows to specify extra behavior options to the ServiceCommand.
Your ServiceCommand implementation class may implement the
Configurable interface and provide the engine with options regarding
execution. For details of the supported options please check the relevant
Service API methods.
Note that currently the only supported option is autoFlush. If you
set it to Boolean.TRUE, which is the default value, it will cause the
engine to flush the audit trail changes after every service call.
AutoFlush must be called if your service calls in your service command depends
on the result of the previous service calls in the same service command.
Please note that flushing will not commit the transaction. The transaction will
be committed as expected at the end of the service call.
In general, using autoFlush will have an impact on the performance of the
service call, because after flushing, objects you are reusing will have to be
refetched from the database. If your service calls you perform in the service
command are independent on each other, e.g. when completing an activity and then
starting another process, or starting several processes in the same transaction,
you may not enable autoFlush.
public class MyServiceCommand implements ServiceCommand, Configurable
{
public Serializable execute(ServiceFactory sf)
{
// do something here
return result;
}
public Map<String, Object> getOptions()
{
return Collections.<String, Object>singletonMap("autoFlush", Boolean.TRUE);
}
}
In specific cases you can switch of the security check for a service via the Stardust property (xxxService.Guarded).
Per default this property is set to true and
the grants set in the Stardust Modeler are active. Please
refer to chapters
Setting Authorization in Model Element Property Pages
of the The Modeling Guide
and
Setting Authorization in Model Element Property Pages of the
Business Process Modeling Handbook
respectively for detailed information on how to set grants in the modelers.
If set to false,
anyone has the grant to use the Workflow Service, but needs to be an administrator
to use the Administration, Query or User Service.
Note
It is not recommended to change this property.
Changing the value to false introduces a high risk of
executing services without having a permission and
hence might cause a severe security hole in the deployment!