Service annotations

The @Service annotation and its companions, with a real example from the manufacturing application.

Source: framework/service/src/com/ilscipio/scipio/service/def/.

@Service#

Defines one service. Place it on a nested public interface inside a container class; the interface itself carries no members.

Attribute	Type	Default	Meaning
`name`	String	`""`	Service name. Defaults to the method or class name in camelCase.
`description`	String	`""`	Service description.
`deprecated`	String	`""`	Deprecation note.
`deprecatedSince`	String	`""`	Version the service was deprecated in.
`deprecatedBy`	String	`""`	Replacement service name.
`implemented`	Implements[]	`{}`	Interfaces this service implements.
`entityAttributes`	EntityAttributes[]	`{}`	Attributes generated from an entity’s fields.
`attributes`	Attribute[]	`{}`	Explicit attribute list.
`overrideAttributes`	OverrideAttribute[]	`{}`	Overrides for attributes an implemented interface already declares.
`auth`	String	`"false"`	Whether a user login is required for the call to succeed.
`permissionService`	PermissionService[]	`{}`	Permission services to check.
`permission`	Permission[]	`{}`	Permissions to check.
`permissions`	Permissions[]	`{}`	Grouped permission checks with a join type.
`export`	String	`"false"`	Whether to export the service as a web service.
`validate`	String	`"true"`	Whether to validate attributes on invocation.
`defaultEntityName`	String	`""`	Entity that `entityAttributes` reads by default.
`useTransaction`	String	`"true"`	Whether to wrap the call in a database transaction.
`requireNewTransaction`	String	`"false"`	Whether to force a new transaction.
`hideResultInLog`	String	`"false"`	Whether to hide the result in the log.
`transactionTimeout`	String	`"0"`	Transaction timeout in seconds. `0` uses the transaction factory default.
`maxRetry`	String	`"-1"`	Max retries when run as a job. `-1` means no limit.
`debug`	String	`""`	Debug flag. Empty means the engine default, `"false"`.
`semaphore`	String	`"none"`	`"none"`, `"fail"` or `"wait"`.
`semaphoreWaitSeconds`	String	`"300"`	Wait time for a `"wait"` semaphore.
`semaphoreSleep`	String	`"500"`	Sleep interval while waiting.
`log`	String	`""`	Logging verbosity: `"normal"`, `"debug"` or `"quiet"`. Empty means `"normal"`.
`logEca`	String	`""`	Logging verbosity when invoked from an ECA. Empty means `"normal"`.
`priority`	String	`""`	Default job priority for async or scheduled runs.
`startDelay`	String	`""`	Fixed start delay in milliseconds.
`engine`	String	`""`	Service engine, for example `"java"`, `"simple"`, `"groovy"`.
`location`	String	`""`	Class or script location the engine invokes.
`invoke`	String	`""`	Method or entry-point name the engine invokes.
`invokes`	GroupInvoke[]	`{}`	For a `"group"` engine, the ordered list of services to run.
`accessorLocation`	String	`""`	Location of the accessor the engine uses.
`accessorInvoke`	String	`""`	Accessor method the engine invokes.
`namespace`	String	`""`	Namespace, for a service exported as a web service.
`namespacePrefix`	String	`""`	Namespace prefix, for a service exported as a web service.
`jobPoolPersist`	String	`""`	Job pool a persisted async run is queued on.
`logTraceExcludeDispatcherRegex`	String	`""`	Dispatcher names excluded from trace logging, as a regular expression.
`metrics`	Metric[]	`{}`	Metrics collected for this service.
`properties`	Property[]	`{}`	Free-form properties, read with `@Property`.

@Attribute#

One explicit service parameter, inside @Service(attributes = {...}).

Attribute	Type	Default	Meaning
`name`	String	required	Attribute name.
`description`	String	`""`	Attribute description.
`type`	String	`""`	Java type name.
`typeCls`	Class	`Object.class`	Java type as a class literal.
`mode`	String	`""`	`"IN"`, `"OUT"` or `"INOUT"`.
`optional`	String	`"false"`	Whether the attribute is optional.
`defaultValue`	String	`""`	Default value when not optional and no value is passed.
`formLabel`	String	`""`	Label for auto-generated forms.
`entityName`	String	`""`	Entity the attribute maps to.
`fieldName`	String	`""`	Entity field the attribute maps to.
`requestAttributeName`	String	`""`	Request attribute name to read from.
`sessionAttributeName`	String	`""`	Session attribute name to read from.
`stringMapPrefix`	String	`""`	Prefix used to collect a string map from request parameters.
`stringListSuffix`	String	`""`	Suffix used to collect a string list from request parameters.
`formDisplay`	String	`"true"`	Whether to include the attribute in auto-generated forms.
`allowHtml`	String	`"none"`	`"none"` or `"any"`.
`typeConvert`	String	`""`	Whether to convert the value to the declared type.
`typeValidate`	TypeValidate[]	`{}`	Validation methods to run.
`access`	String	`""`	`"public"` or `"internal"`.
`eventAccess`	String	`""`	Access level from an event context.
`inject`	String	`""`	Whether to inject the default value onto a protected field.

@EntityAttributes#

Generates a block of attributes from an entity’s own fields, inside @Service(entityAttributes = {...}).

Attribute	Type	Default	Meaning
`entityName`	String	`""`	Entity to read fields from. Defaults to the service’s `defaultEntityName`.
`prefix`	String	`""`	Prefix added to each generated attribute name.
`mode`	String	required	`"IN"`, `"OUT"` or `"INOUT"`.
`include`	String	`"all"`	`"all"`, `"pk"` or `"nonpk"`.
`optional`	String	`"false"`	Whether the generated attributes are optional.
`formDisplay`	String	`"true"`	Whether to include the attributes in auto-generated forms.
`allowHtml`	String	`"none"`	`"none"` or `"any"`.
`typeConvert`	String	`""`	Whether to convert values to the declared type.
`excludeFields`	String[]	`{}`	Fields to exclude from generation.
`access`	String	`""`	`"public"` or `"internal"`.
`eventAccess`	String	`""`	Access level from an event context.

@OverrideAttribute#

Overrides one attribute an implemented interface already declares, inside @Service(overrideAttributes = {...}). Same attribute names as @Attribute except name and type keep their meaning and every other field defaults to "" (unset, meaning inherit).

@Implements#

Declares that this service reuses another service’s interface, inside @Service(implemented = {...}).

Attribute	Type	Default	Meaning
`service`	String	`""`	Service whose interface (attributes) this service implements.
`optional`	String	`"false"`	Whether the implemented definition may be missing.

@Permission / @Permissions / @PermissionService#

Annotation	Attribute	Type	Default	Meaning
`@Permission`	`permission`	String	required	Permission id to check.
`@Permission`	`action`	String	`""`	Action suffix, for example `_VIEW`.
`@Permissions`	`joinType`	String	`""`	`"OR"` or `"AND"` across the group. Empty means `"OR"`.
`@Permissions`	`permissions`	Permission[]	`{}`	Permissions in the group.
`@Permissions`	`services`	PermissionService[]	`{}`	Permission services in the group.
`@PermissionService`	`service`	String	required	Service that checks the permission.
`@PermissionService`	`resourceDescription`	String	`""`	Text used in error messages. Defaults to the service name.
`@PermissionService`	`mainAction`	String	`""`	Action passed to the permission service.

@Property#

One property passed to the service engine, inside @Service(properties = {...}).

Attribute	Type	Default	Meaning
`name`	String	required	Property name.
`description`	String	`""`	Property description.
`type`	String	`""`	Property type.
`value`	String	`""`	Property value.

@TypeValidate#

One validation method, inside @Attribute(typeValidate = {...}).

Attribute	Type	Default	Meaning
`method`	String	required	Static method name to call.
`className`	String	`"org.ofbiz.base.util.UtilValidate"`	Class the method lives on.
`failMessage`	String	`""`	Message on failure.
`failProperty`	String	`""`	Properties key for the failure message.
`failResource`	String	`""`	Resource bundle the failure message comes from.

@Seca and @SecaAction#

A SECA (Service Event Condition Action) runs one or more actions when a source service reaches an event. Source: framework/service/src/com/ilscipio/scipio/service/def/seca/.

Annotation	Attribute	Type	Default	Meaning
`@Seca`	`service`	String	`""`	Source service to attach to. Defaults to the annotated service.
`@Seca`	`event`	String	required	`global-commit`, `global-commit-post-run`, `global-rollback`, `auth`, `in-validate`, `out-validate`, `invoke`, `commit`, `return`.
`@Seca`	`runOnFailure`	String	`"false"`	Run the action if the source service returns failure.
`@Seca`	`runOnError`	String	`"false"`	Run the action if the source service returns error.
`@Seca`	`enabled`	String	`"true"`	Enables or disables the SECA.
`@Seca`	`condition`	String	`""`	Condition expression.
`@Seca`	`assignments`	SecaSet[]	`{}`	Field assignments before the action runs.
`@Seca`	`actions`	SecaAction[]	`{}`	Actions to run.
`@SecaAction`	`service`	String	`""`	Service to invoke. Defaults to the annotated service.
`@SecaAction`	`mode`	String	`"sync"`	`"sync"` or `"async"`.
`@SecaAction`	`runAsUser`	String	`""`	User to run as. Defaults to the currently running user.
`@SecaAction`	`resultMapName`	String	`""`	Name to store the result under.
`@SecaAction`	`newTransaction`	String	`"false"`	Whether to run in a new transaction.
`@SecaAction`	`resultToContext`	String	`"true"`	Whether to inject the result into the next service’s context.
`@SecaAction`	`resultToResult`	String	`"false"`	Whether to copy the result into the source service’s own result.
`@SecaAction`	`ignoreFailure`, `ignoreError`	String	`""`	Ignore a failure or error result.
`@SecaAction`	`persist`	String	`""`	Persist the job.
`@SecaAction`	`priority`	String	`""`	Job priority, 0-100. Defaults to 50.
`@SecaAction`	`jobPool`	String	`""`	Job pool to run in, when `persist="false"`.
`@SecaAction`	`assignments`	SecaSet[]	`{}`	Field assignments before the invocation.

@Eeca and @EecaAction#

An EECA (Entity Event Condition Action) runs one or more actions when an entity operation reaches an event. Source: framework/service/src/com/ilscipio/scipio/service/def/eeca/.

Annotation	Attribute	Type	Default	Meaning
`@Eeca`	`entity`	String	required	Entity name.
`@Eeca`	`operation`	String	required	`create`, `store`, `remove`, `find`, `create-store`, `create-remove`, `store-remove`, `create-store-remove` or `any`.
`@Eeca`	`event`	String	required	`validate`, `run`, `return`, `cache-check`, `cache-put`, `cache-clear`.
`@Eeca`	`runOnError`	String	`"false"`	Run the action if the entity operation returns error.
`@Eeca`	`enabled`	String	`"true"`	Enables or disables the EECA.
`@Eeca`	`condition`	String	`""`	Condition expression.
`@Eeca`	`assignments`	EecaSet[]	`{}`	Field assignments before the action runs.
`@Eeca`	`actions`	EecaAction[]	`{}`	Actions to run.
`@EecaAction`	`service`	String	`""`	Service to invoke. Defaults to the annotated service.
`@EecaAction`	`mode`	String	`"sync"`	`"sync"` or `"async"`.
`@EecaAction`	`resultToValue`	String	`"true"`	Transfer the service result onto the entity value.
`@EecaAction`	`abortOnError`	String	`"false"`	Abort on error.
`@EecaAction`	`rollbackOnError`	String	`"false"`	Roll back the transaction on error.
`@EecaAction`	`persist`	String	`"false"`	Persist the job.
`@EecaAction`	`runAsUser`	String	`""`	User to run as. Defaults to `"system"`.
`@EecaAction`	`valueAttr`	String	`""`	Attribute name the entity value is passed under.
`@EecaAction`	`priority`	String	`""`	Job priority, 0-100. Defaults to 50.
`@EecaAction`	`jobPool`	String	`""`	Job pool to run in, when `persist="false"`.
`@EecaAction`	`reloadValue`	String	`"false"`	Reload the value before running.
`@EecaAction`	`assignments`	EecaSet[]	`{}`	Field assignments before the invocation.

Example: `createBOMAssoc`#

applications/manufacturing/src/com/ilscipio/scipio/manufacturing/service/BomServices.java, lines 33-51.

java
@Service(
    name = "createBOMAssoc",
    engine = "java",
    location = "com.ilscipio.scipio.manufacturing.event.BomSimpleMethods",
    invoke = "createBOMAssoc",
    description = "Add Product to Product Association",
    defaultEntityName = "ProductAssoc",
    auth = "true",
    entityAttributes = {
        @EntityAttributes(mode = "IN", include = "pk"),
        @EntityAttributes(mode = "IN", include = "nonpk", optional = "true")
    },
    attributes = {
        @Attribute(name = "errorMessage", type = "String", mode = "OUT", optional = "true")
    },
    overrideAttributes = {
        @OverrideAttribute(name = "fromDate", optional = "true")
    }
)
public interface CreateBOMAssoc {}

The equivalent XML <service> element:

xml
<service name="createBOMAssoc" engine="java"
    location="com.ilscipio.scipio.manufacturing.event.BomSimpleMethods" invoke="createBOMAssoc"
    default-entity-name="ProductAssoc" auth="true"
    description="Add Product to Product Association">
    <auto-attributes include="pk" mode="IN" optional="false"/>
    <auto-attributes include="nonpk" mode="IN" optional="true"/>
    <override name="fromDate" optional="true"/>
    <attribute name="errorMessage" type="String" mode="OUT" optional="true"/>
</service>