org.bonitasoft.engine.api

Interface CommandAPI

public interface CommandAPI

Manipulate tenant commands. A command can be registered, unregistered, and executed with parameters.

Commands are used to extend engine behavior, and are classes that are called from this API and executed on the server side.

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");
 
 

Author:

Matthieu Chaffotte, Yanyan Liu, Celine Souchet, Baptiste Mesta, Emmanuel Duchastenier

See Also:

CommandDescriptor, register(String, String, String), unregister(long), addDependency(String, byte[]), removeDependency(String)

Method Summary

Methods

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.

Method Detail

addDependency

void addDependency(String name,
                 byte[] jar)
                   throws AlreadyExistsException,
                          CreationException

Adds a dependency to the tenant scope.

Parameters:

name - the dependency name

jar - the JAR content

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

AlreadyExistsException - if a dependency with the same name already exists

CreationException - occurs when any other dependency creation problem occurs

Since:

6.0

removeDependency

void removeDependency(String name)
                      throws DependencyNotFoundException,
                             DeletionException

Remove a dependency to the tenant scope.

Parameters:

name - the dependency name.

Throws:

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 dependency

DeletionException - occurs when an exception is thrown during dependency deletion

Since:

6.0

register

CommandDescriptor register(String name,
                         String description,
                         String implementation)
                           throws AlreadyExistsException,
                                  CreationException

Create a new command with its provided name, description, implementation.

Parameters:

name - the command name

description - the descriptor of the command

implementation - the implementation class which will be uses when executing the command. This class is inside the jar.

Returns:

the descriptor of the newly created command

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

AlreadyExistsException - when a command with the same name already exists

CreationException - when the command registering cannot be fulfilled

Since:

6.0

execute

Serializable execute(String name,
                   Map<String,Serializable> parameters)
                     throws CommandNotFoundException,
                            CommandParameterizationException,
                            CommandExecutionException

Execute a command according to its name and a map of parameters.

Parameters:

name - the command name

parameters - the parameters

Returns:

the result of the command execution.

Throws:

InvalidSessionException - 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

CommandParameterizationException - when command parameters are not correct

CommandExecutionException - occurs when an exception is thrown during command execution

Since:

6.0

executeWithUserTransactions

Serializable executeWithUserTransactions(String name,
                                       Map<String,Serializable> parameters)
                                         throws CommandNotFoundException,
                                                CommandParameterizationException,
                                                CommandExecutionException

Execute a command according to its name and a map of parameters. During the execution of this method, the command's implementation will have to manage itself its transactions.

Parameters:

name - the command name

parameters - the parameters

Returns:

the result of the command execution.

Throws:

InvalidSessionException - 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

CommandParameterizationException - when command parameters are not correct

CommandExecutionException - occurs when an exception is thrown during command execution

Since:

6.2

execute

Serializable execute(long commandId,
                   Map<String,Serializable> parameters)
                     throws CommandNotFoundException,
                            CommandParameterizationException,
                            CommandExecutionException

Execute a command according to its id and a map of parameters.

Parameters:

commandId - the command commandId

parameters - the parameters

Returns:

the result of the command execution.

Throws:

InvalidSessionException - 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

CommandParameterizationException - when command parameters are not correct

CommandExecutionException - occurs when an exception is thrown during command execution

Since:

6.0

executeWithUserTransactions

Serializable executeWithUserTransactions(long commandId,
                                       Map<String,Serializable> parameters)
                                         throws CommandNotFoundException,
                                                CommandParameterizationException,
                                                CommandExecutionException

Execute a command according to its id and a map of parameters. During the execution of this method, the command's implementation will have to manage itself its transactions.

Parameters:

commandId - the command commandId

parameters - the parameters

Returns:

the result of the command execution.

Throws:

InvalidSessionException - 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

CommandParameterizationException - when command parameters are not correct

CommandExecutionException - occurs when an exception is thrown during command execution

Since:

6.2

unregister

void unregister(String name)
                throws CommandNotFoundException,
                       DeletionException

Delete a command through its name.

Parameters:

name - the command name

Throws:

InvalidSessionException - 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 deletion

Since:

6.0

getCommand

CommandDescriptor getCommand(String name)
                             throws CommandNotFoundException

Returns the command descriptor

Parameters:

name - the command name

Returns:

the descriptor of the command

Throws:

InvalidSessionException - 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.

Since:

6.0

getAllCommands

List<CommandDescriptor> getAllCommands(int startIndex,
                                     int maxResults,
                                     CommandCriterion sort)

Returns the paginated list of command descriptors according to the sort criterion.

Parameters:

startIndex - the list start index

maxResults - the number of CommandDescriptor to retrieve

sort - the sorting criterion

Returns:

the paginated list of descriptors of the command

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

Since:

6.0

update

void update(String name,
          CommandUpdater updateDescriptor)
            throws CommandNotFoundException,
                   UpdateException

Updates a command according to the update descriptor.

Parameters:

name - the command name

updateDescriptor - the update descriptor

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

CommandNotFoundException - when the name does not refer to any existing command

UpdateException - when the update cannot be fulfilled correctly

Since:

6.0

unregisterAll

void unregisterAll()
                   throws DeletionException

Delete all commands

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

DeletionException - occurs when an exception is thrown during command (unregistering) deletion

Since:

6.0

getUserCommands

List<CommandDescriptor> getUserCommands(int startIndex,
                                      int maxResults,
                                      CommandCriterion sort)

Returns the Commands with System is false

Parameters:

startIndex - The starting index

maxResults - The number of CommandDescriptor

sort - The sorting criterion

Returns:

The list of commands

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

Since:

6.0

get

CommandDescriptor get(long commandId)
                      throws CommandNotFoundException

Get the command descriptor by its id

Parameters:

commandId - identifier of command

Returns:

the descriptor of the command

Throws:

InvalidSessionException - 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.

Since:

6.0

update

void update(long commandId,
          CommandUpdater updateDescriptor)
            throws CommandNotFoundException,
                   UpdateException

Updates a command according to the update descriptor.

Parameters:

commandId - identifier of command to indicate which command will be updated

updateDescriptor - the update descriptor

Throws:

InvalidSessionException - 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

UpdateException - occurs when an exception is thrown during command update

Since:

6.0

unregister

void unregister(long commandId)
                throws CommandNotFoundException,
                       DeletionException

Delete a command through its id.

Parameters:

commandId - the identifier of command

Throws:

InvalidSessionException - 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 deletion

Since:

6.0

searchCommands

SearchResult<CommandDescriptor> searchCommands(SearchOptions searchOptions)
                                               throws SearchException

Search commands

Parameters:

searchOptions - The criterion used during the search

Returns:

A SearchResult containing the search result

Throws:

InvalidSessionException - Generic exception thrown if API Session is invalid, e.g session has expired.

SearchException - when problem occurs during the commands search

Since:

6.0