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 implementsTenantCommand
isorg.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)
Add 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 descriptor of the command by its identifier.
|
List<CommandDescriptor> |
getAllCommands(int startIndex,
int maxResults,
CommandCriterion sort)
Get the paginated list of the descriptors of the command according to the sort criterion.
|
CommandDescriptor |
getCommand(String name)
Get the descriptor of the command.
|
List<CommandDescriptor> |
getUserCommands(int startIndex,
int maxResults,
CommandCriterion sort)
Get the list of the descriptor of the user commands (no system command).
|
CommandDescriptor |
register(String name,
String description,
String implementation)
Create a new command.
|
void |
removeDependency(String name)
Remove a dependency to the tenant scope.
|
SearchResult<CommandDescriptor> |
searchCommands(SearchOptions searchOptions)
Search commands corresponding to the criteria.
|
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)
Update a command according to the update descriptor.
|
void |
update(String name,
CommandUpdater updateDescriptor)
Update a command according to the update descriptor.
|
void addDependency(String name, byte[] jar) throws AlreadyExistsException, CreationException
name
- The name of the dependency.jar
- The JAR content of the dependency.InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.AlreadyExistsException
- If a dependency with the same name already existsCreationException
- If an other problem occursvoid removeDependency(String name) throws DependencyNotFoundException, DeletionException
name
- The name of the dependency.InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.DependencyNotFoundException
- If the name does not refer to any existing dependencyDeletionException
- If an other problem occursCommandDescriptor register(String name, String description, String implementation) throws AlreadyExistsException, CreationException
name
- The name of the commanddescription
- The description of the commandimplementation
- The name of the implementation class of the command. It will be used when executing the command. This class is inside the jar of a dependency.InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.AlreadyExistsException
- If a command with the same name already existsCreationException
- If an other problem occursSerializable execute(String name, Map<String,Serializable> parameters) throws CommandNotFoundException, CommandParameterizationException, CommandExecutionException
name
- The name of the commandparameters
- The parameters of the commandInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- If the name does not refer to any existing commandCommandParameterizationException
- If a parameter of the command is not correctCommandExecutionException
- If an other problem occursSerializable executeWithUserTransactions(String name, Map<String,Serializable> parameters) throws CommandNotFoundException, CommandParameterizationException, CommandExecutionException
name
- The name of the commandparameters
- The parameters of the commandInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- If the name does not refer to any existing commandCommandParameterizationException
- If a parameter of the command is not correctCommandExecutionException
- If an other problem occursSerializable execute(long commandId, Map<String,Serializable> parameters) throws CommandNotFoundException, CommandParameterizationException, CommandExecutionException
commandId
- The identifier of the commandparameters
- The parameters of the commandInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- If the name does not refer to any existing commandCommandParameterizationException
- If a parameter of the command is not correctCommandExecutionException
- If an other problem occursSerializable executeWithUserTransactions(long commandId, Map<String,Serializable> parameters) throws CommandNotFoundException, CommandParameterizationException, CommandExecutionException
commandId
- The identifier of the commandparameters
- The parameters of the commandInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- If the name does not refer to any existing commandCommandParameterizationException
- If a parameter of the command is not correctCommandExecutionException
- If an other problem occursvoid unregister(String name) throws CommandNotFoundException, DeletionException
name
- The name of the commandInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- If the name does not refer to any existing command.DeletionException
- If an other problem occursCommandDescriptor getCommand(String name) throws CommandNotFoundException
name
- The name of the commandInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- If an other problem occursList<CommandDescriptor> getAllCommands(int startIndex, int maxResults, CommandCriterion sort)
startIndex
- The index of the first element to be retrieved (it starts from zero)maxResults
- The number of CommandDescriptor
to get.sort
- The sorting criterion of the list.InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.void update(String name, CommandUpdater updateDescriptor) throws CommandNotFoundException, UpdateException
name
- The name of the commandupdateDescriptor
- The update descriptor (containing the fields to update & their new value).InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- If the name does not refer to any existing commandUpdateException
- If an other problem occurs.void unregisterAll() throws DeletionException
InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.DeletionException
- If an other problem occurs.List<CommandDescriptor> getUserCommands(int startIndex, int maxResults, CommandCriterion sort)
startIndex
- The index of the first element to be retrieved (it starts from zero)maxResults
- The number of CommandDescriptor
to get.sort
- The sorting criterion of the list.InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandDescriptor get(long commandId) throws CommandNotFoundException
commandId
- The identifier of commandInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- If the identifier does not refer to any existing command.void update(long commandId, CommandUpdater updateDescriptor) throws CommandNotFoundException, UpdateException
commandId
- The identifier of command to update.updateDescriptor
- The update descriptorInvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.CommandNotFoundException
- If the identifier does not refer to any existing command.UpdateException
- If an other problem occurs.void 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
- If the name does not refer to any existing command.DeletionException
- If an other problem occurs.SearchResult<CommandDescriptor> searchCommands(SearchOptions searchOptions) throws SearchException
searchOptions
- The criterion used during the searchSearchResult
containing the descriptor of the commands.InvalidSessionException
- Generic exception thrown if API Session is invalid, e.g session has expired.SearchException
- If an other problem occurs.Copyright © 2018 Bonitasoft S.A.. All rights reserved.