Declaring a user service

Declaration interface

The following table lists, per nature, the interface that the declaration class of a user service must implement:

Life cycle and threading model

The user service declaration class is instantiated at the TIBCO EBX® startup and must be coded to be thread-safe. This is usually not an issue as most implementations should be immutable classes.

Registration

A user service declaration must be registered by a module or a data model.

Registration by a module is achieved by the module registration servlet by a code similar to:

public class CustomRegistrationServlet extends ModuleRegistrationServlet 
{
	@Override
	public void handleServiceRegistration(ModuleServiceRegistrationContext aContext)
	{
		// Register custom user service declaration.
		aContext.registerUserService(new CustomServiceDeclaration());
	}
}

For more information on the module registration servlet, see module registration and ModuleRegistrationServlet.

Registration by a data model is achieved by a code similar to:

public class CustomSchemaExtensions implements SchemaExtensions
{
	@Override
	public void defineExtensions(SchemaExtensionsContext aContext)
	{
		// Register custom user service declaration.
		aContext.registerUserService(new CustomServiceDeclaration());
	}
}

For more information on data model extensions, see SchemaExtensions.

Service properties

The properties of a user service include its label, description, confirmation message and the group that owns the service. All are optional but it is a good practice to at least define the label.

For more information, see UserServiceDeclaration.defineProperties.

Service activation scope

The activation scope defines on which selection the service is available.

Example of a service activation definition:

public class CustomServiceDeclaration implements UserServiceDeclaration.OnTableView
{	
	...
	
	@Override
	public void defineActivation(ActivationContextOnTableView aContext)
	{
		// activates the service in all dataspaces except the "Reference" branch.
		aContext.includeAllDataspaces(DataspaceType.BRANCH);
		aContext.excludeDataspacesMatching(Repository.REFERENCE, DataspaceChildrenPolicy.NONE);

		// activates the service only on tables "table01" and "table03".
		aContext.includeSchemaNodesMatching(
			CustomDataModelPath._Root_Table01.getPathInSchema(),
			CustomDataModelPath._Root_Table03.getPathInSchema());

		// service will be enabled only when at least one record is selected.
		aContext.forbidEmptyRecordSelection();

		// service will not be displayed in hierarchical views (neither in the
		// top toolbar, nor in the hierarchy nodes' menu).
		aContext.setDisplayForLocations(
			ActionDisplaySpec.HIDDEN,
			ToolbarLocation.HIERARCHICAL_VIEW_TOP,
			ToolbarLocation.HIERARCHICAL_VIEW_NODE);

		// service will be considered as disabled if not explicitly enabled
		// via the UI.
		aContext.setDefaultPermission(UserServicePermission.getDisabled());
	}
}

For more information about declaring the activation scope, see UserServiceDeclaration.defineActivation.

For more information about the resolution of the user service availability, see Resolving permissions on services.

Web component declaration

Parameters declaration and availability in workflows and perspectives

User services are automatically available as web components with a set of built-in parameters depending on the service's nature. To define custom parameters and/or set the service web component as available when configuring a workflow user task, a perspective menu action or a toolbar web component action, UserServiceDeclaration.declareWebComponent must be used.

Example of a web component declaration:

public class CustomServiceDeclaration implements UserServiceDeclaration.OnDataset
{
	...
	
	@Override
	public void declareWebComponent(WebComponentDeclarationContext aContext)
	{
		// makes this web component available when configuring a workflow user task.
		aContext.setAvailableAsWorkflowUserTask(true);

		// adds a custom input parameter.
		aContext.addInputParameter(
			"source",
			UserMessage.createInfo("Source"),
			UserMessage.createInfo("Source of the imported data."));
		
		// modifies the built-in "instance" parameter to be "input/output" instead of "input".
		aContext.getBuiltInParameterForOverride("instance").setOutput(true);
	}
}

See Using TIBCO EBX® as a Web Component for more information.

User service extension

It is possible to extend existing user services (built-in or custom) in order to add input/output parameters when using these services as web components.

In order to do so, a user service extension must first be registered by a module or a data model.

Registration by a module is achieved by the module registration servlet by code similar to:

public class CustomRegistrationServlet extends ModuleRegistrationServlet 
{
	...
	
	@Override
	public void handleServiceRegistration(ModuleServiceRegistrationContext aContext)
	{
		// Register user service extension declaration.
		aContext.registerUserServiceExtension(new ServiceExtensionDeclaration());
	}
}

For more information on the module registration servlet, see module registration and ModuleRegistrationServlet.

Registration by a data model is achieved by a code similar to:

public class CustomSchemaExtensions implements SchemaExtensions
{
	...
	
	@Override
	public void defineExtensions(SchemaExtensionsContext aContext)
	{
		// Register user service extension declaration.
		aContext.registerUserServiceExtension(new ServiceExtensionDeclaration());
	}
}

For more information on the data model extension, see SchemaExtensions.

User service groups

User service groups are used to organize the display of user services in menus and permission management screens.

The following types of service groups are available:

• Built-in User Service Groups provided by EBX®,

• Custom User Service Groups declared in a module.

The link between groups and services is made upon service declaration. See Associating a service to a group.

Built-in User Service Groups

Available built-in service groups:

Declaring a User Service Group

User Service Groups must be declared while registering the module, using the method ModuleServiceRegistrationContext.registerServiceGroup:

public class CustomRegistrationServlet extends ModuleRegistrationServlet 
{
	...
	
	@Override
	public void handleServiceRegistration(ModuleServiceRegistrationContext aContext)
	{
		// In CustomModuleConstants,
		// CUSTOM_SERVICE_GROUP_KEY = ServiceGroupKey.forServiceGroupInModule("customModule", "customGroup")
		
		// registers CUSTOM_SERVICE_GROUP_KEY service group
		aContext.registerServiceGroup(
			CustomModuleConstants.CUSTOM_SERVICE_GROUP_KEY,
			UserMessage.createInfo("Custom group"),
			UserMessage.createInfo("This group contains services related to..."));
	}
}

Associating a service to a group

The association of a service with a group is made at its declaration, using the method UserServicePropertiesDefinitionContext.setGroup:

public class CustomServiceDeclaration implements UserServiceDeclaration.OnDataset
{
	...
	
	@Override
	public void defineProperties(UserServicePropertiesDefinitionContext aContext)
	{
		// associates the current service to the CUSTOM_SERVICE_GROUP_KEY group
		aContext.setGroup(CustomModuleConstants.CUSTOM_SERVICE_GROUP_KEY);
	}
}

A service can be associated with either a built-in or a custom service group. In the latter case, this service will be displayed in this built-in group, just like other built-in services belonging to this group.