public interface CommandAPI
Commands are used to extend engine behavior, and are classes that are called from this API and executed on the server side.
in the execute method of this class.
A command is composed of a jar containing at least one class that implements org.bonitasoft.engine.command.TenantCommand.
org.bonitasoft.engine.command.system.CommandWithParameters can be used to handle parameter more easily. The behavior of the command must be defined in the
execute method of this class.
TenantCommand is a class available only in bonita-server.jar. In order to create the jar you will need to have a dependency on that jar.
The jar containing the command class must be added to the engine using the addDependency(java.lang.String, byte[])
method with a name to identify the dependency so
that it can be removed later.
Then the command must be registered using register(String, String, String)
with a name to identify it and an implementation that is the
fully qualified name of the command class.
After registration, the command can be executed using execute(long, Map)
with the id returned by the register method or
execute(String, Map)
with the name of the command and with a map of parameters required by the command.
Finally the command can be removed using both unregister(long)
or unregister(String)
and
removeDependency(String)
Code example:
In this example we deploy a command named "myCommandName". The class that implements TenantCommand is org.bonitasoft.engine.command.IntegerCommand and is contained in the jar we deploy using CommandAPI.addDependency.byte[] byteArray = /* read the jar containing the command as a byte array * / //deploy getCommandAPI().addDependency("myCommandDependency", byteArray); getCommandAPI().register("myCommandName", "Retrieving the integer value", "org.bonitasoft.engine.command.IntegerCommand"); //execute final Map<String, Serializable> parameters = new HashMap<String, Serializable>(); parameters.put("aParamterName", "aParameterValue"); parameters.put("anIntParameter", 42); Integer theResultOfTheCommandExecution = (Integer) getCommandAPI().execute("myCommandName", parameters); //undeploy getCommandAPI().unregister("myCommandName"); getCommandAPI().removeDependency("myCommandDependency");
CommandDescriptor
,
register(String, String, String)
,
unregister(long)
,
addDependency(String, byte[])
,
removeDependency(String)
Modifier and Type | Method and Description |
---|---|
void |
addDependency(String name,
byte[] jar)
Adds a dependency to the tenant scope.
|
Serializable |
execute(long commandId,
Map<String,Serializable> parameters)
Execute a command according to its id and a map of parameters.
|
Serializable |
execute(String name,
Map<String,Serializable> parameters)
Execute a command according to its name and a map of parameters.
|
Serializable |
executeWithUserTransactions(long commandId,
Map<String,Serializable> parameters)
Execute a command according to its id and a map of parameters.
|
Serializable |
executeWithUserTransactions(String name,
Map<String,Serializable> parameters)
Execute a command according to its name and a map of parameters.
|
CommandDescriptor |
get(long commandId)
Get the command descriptor by its id
|
List<CommandDescriptor> |
getAllCommands(int startIndex,
int maxResults,
CommandCriterion sort)
Returns the paginated list of command descriptors according to the sort criterion.
|
CommandDescriptor |
getCommand(String name)
Returns the command descriptor
|
List<CommandDescriptor> |
getUserCommands(int startIndex,
int maxResults,
CommandCriterion sort)
Returns the Commands with System is false
|
CommandDescriptor |
register(String name,
String description,
String implementation)
Create a new command with its provided name, description, implementation.
|
void |
removeDependency(String name)
Remove a dependency to the tenant scope.
|
SearchResult<CommandDescriptor> |
searchCommands(SearchOptions searchOptions)
Search commands
|
void |
unregister(long commandId)
Delete a command through its id.
|
void |
unregister(String name)
Delete a command through its name.
|
void |
unregisterAll()
Delete all commands
|
void |
update(long commandId,
CommandUpdater updateDescriptor)
Updates a command according to the update descriptor.
|
void |
update(String name,
CommandUpdater updateDescriptor)
Updates a command according to the update descriptor.
|
void addDependency(String name, byte[] jar) throws AlreadyExistsException, CreationException
name
- the dependency namejar
- the JAR contentInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.AlreadyExistsException
- if a dependency with the same name already existsCreationException
- occurs when any other dependency creation problem occursvoid removeDependency(String name) throws DependencyNotFoundException, DeletionException
name
- the dependency name.InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.DependencyNotFoundException
- occurs when the name does not refer to any existing dependencyDeletionException
- occurs when an exception is thrown during dependency deletionCommandDescriptor register(String name, String description, String implementation) throws AlreadyExistsException, CreationException
name
- the command namedescription
- the descriptor of the commandimplementation
- the implementation class which will be uses when executing the command. This class is inside the jar.InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.AlreadyExistsException
- when a command with the same name already existsCreationException
- when the command registering cannot be fulfilledSerializable execute(String name, Map<String,Serializable> parameters) throws CommandNotFoundException, CommandParameterizationException, CommandExecutionException
name
- the command nameparameters
- the parametersInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- occurs when the name does not refer to any existing commandCommandParameterizationException
- when command parameters are not correctCommandExecutionException
- occurs when an exception is thrown during command executionSerializable executeWithUserTransactions(String name, Map<String,Serializable> parameters) throws CommandNotFoundException, CommandParameterizationException, CommandExecutionException
name
- the command nameparameters
- the parametersInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- occurs when the name does not refer to any existing commandCommandParameterizationException
- when command parameters are not correctCommandExecutionException
- occurs when an exception is thrown during command executionSerializable execute(long commandId, Map<String,Serializable> parameters) throws CommandNotFoundException, CommandParameterizationException, CommandExecutionException
commandId
- the command commandIdparameters
- the parametersInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- occurs when the name does not refer to any existing commandCommandParameterizationException
- when command parameters are not correctCommandExecutionException
- occurs when an exception is thrown during command executionSerializable executeWithUserTransactions(long commandId, Map<String,Serializable> parameters) throws CommandNotFoundException, CommandParameterizationException, CommandExecutionException
commandId
- the command commandIdparameters
- the parametersInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- occurs when the name does not refer to any existing commandCommandParameterizationException
- when command parameters are not correctCommandExecutionException
- occurs when an exception is thrown during command executionvoid unregister(String name) throws CommandNotFoundException, DeletionException
name
- the command nameInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- occurs when the name does not refer to any existing command.DeletionException
- occurs when an exception is thrown during command deletionCommandDescriptor getCommand(String name) throws CommandNotFoundException
name
- the command nameInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- occurs when the command name does not refer to any existing command.List<CommandDescriptor> getAllCommands(int startIndex, int maxResults, CommandCriterion sort)
startIndex
- the list start indexmaxResults
- the number of CommandDescriptor
to retrievesort
- the sorting criterionInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.void update(String name, CommandUpdater updateDescriptor) throws CommandNotFoundException, UpdateException
name
- the command nameupdateDescriptor
- the update descriptorInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- when the name does not refer to any existing commandUpdateException
- when the update cannot be fulfilled correctlyvoid unregisterAll() throws DeletionException
InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.DeletionException
- occurs when an exception is thrown during command (unregistering) deletionList<CommandDescriptor> getUserCommands(int startIndex, int maxResults, CommandCriterion sort)
startIndex
- The starting indexmaxResults
- The number of CommandDescriptor
sort
- The sorting criterionInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandDescriptor get(long commandId) throws CommandNotFoundException
commandId
- identifier of commandInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- occurs when the command id does not refer to any existing command.void update(long commandId, CommandUpdater updateDescriptor) throws CommandNotFoundException, UpdateException
commandId
- identifier of command to indicate which command will be updatedupdateDescriptor
- the update descriptorInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- occurs when the command id does not refer to any existing commandUpdateException
- occurs when an exception is thrown during command updatevoid unregister(long commandId) throws CommandNotFoundException, DeletionException
commandId
- the identifier of commandInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- occurs when the name does not refer to any existing command.DeletionException
- occurs when an exception is thrown during command deletionSearchResult<CommandDescriptor> searchCommands(SearchOptions searchOptions) throws SearchException
searchOptions
- The criterion used during the searchSearchResult
containing the search resultInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.SearchException
- when problem occurs during the commands searchCopyright © 2014 Bonitasoft S.A.. All rights reserved.