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

Since:

6.0.0

Version:

6.4.1

Author:

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

See Also:

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

Method Summary

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.

Method Detail

addDependency

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

Add a dependency to the tenant scope.

Parameters:

name - The name of the dependency.

jar - The JAR content of the dependency.

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 - If an other problem occurs

Since:

6.0

removeDependency

void removeDependency(String name)
               throws DependencyNotFoundException,
                      DeletionException

Remove a dependency to the tenant scope.

Parameters:

name - The name of the dependency.

Throws:

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

DependencyNotFoundException - If the name does not refer to any existing dependency

DeletionException - If an other problem occurs

Since:

6.0

register

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

Create a new command.

Parameters:

name - The name of the command

description - The description of the command

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

Returns:

The descriptor of the newly created command

Throws:

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

AlreadyExistsException - If a command with the same name already exists

CreationException - If an other problem occurs

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 name of the command

parameters - The parameters of the command

Returns:

The result of the command execution.

Throws:

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

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

CommandParameterizationException - If a parameter of the command is not correct

CommandExecutionException - If an other problem occurs

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 name of the command

parameters - The parameters of the command

Returns:

The result of the command execution.

Throws:

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

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

CommandParameterizationException - If a parameter of the command is not correct

CommandExecutionException - If an other problem occurs

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 identifier of the command

parameters - The parameters of the command

Returns:

The result of the command execution.

Throws:

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

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

CommandParameterizationException - If a parameter of the command is not correct

CommandExecutionException - If an other problem occurs

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 identifier of the command

parameters - The parameters of the command

Returns:

The result of the command execution.

Throws:

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

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

CommandParameterizationException - If a parameter of the command is not correct

CommandExecutionException - If an other problem occurs

Since:

6.2

unregister

void unregister(String name)
         throws CommandNotFoundException,
                DeletionException

Delete a command through its name.

Parameters:

name - The name of the command

Throws:

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

Since:

6.0

getCommand

CommandDescriptor getCommand(String name)
                      throws CommandNotFoundException

Get the descriptor of the command.

Parameters:

name - The name of the command

Returns:

The descriptor of the command

Throws:

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

CommandNotFoundException - If an other problem occurs

Since:

6.0

getAllCommands

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

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

Parameters:

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.

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

Update a command according to the update descriptor.

Parameters:

name - The name of the command

updateDescriptor - The update descriptor (containing the fields to update & their new value).

Throws:

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

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

UpdateException - If an other problem occurs.

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 - If an other problem occurs.

Since:

6.0

getUserCommands

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

Get the list of the descriptor of the user commands (no system command).

Parameters:

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.

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

get

CommandDescriptor get(long commandId)
               throws CommandNotFoundException

Get the descriptor of the command by its identifier.

Parameters:

commandId - The 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 - If the identifier does not refer to any existing command.

Since:

6.0

update

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

Update a command according to the update descriptor.

Parameters:

commandId - The identifier of command to update.

updateDescriptor - The update descriptor

Throws:

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

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 - If the name does not refer to any existing command.

DeletionException - If an other problem occurs.

Since:

6.0

searchCommands

SearchResult<CommandDescriptor> searchCommands(SearchOptions searchOptions)
                                        throws SearchException

Search commands corresponding to the criteria.

Parameters:

searchOptions - The criterion used during the search

Returns:

A SearchResult containing the descriptor of the commands.

Throws:

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

SearchException - If an other problem occurs.

Since:

6.0