Interface ExceptionHandlerService
- All Superinterfaces:
com.appiancorp.services.ContextSensitiveService
,Service
Process exception handling is used for raising exceptions on processes or tasks when something goes wrong so that particular users (identified by their role for the process or task) can be notified of the problem and given a recommended course of action.
All exception types must first be registered using
registerExceptionTypesWithNotes(com.appiancorp.suiteapi.process.ProcessExceptionType[], java.lang.String[])
. See
ProcessExceptionType
for more information on how to configure a
ProcessExceptionType
before registering it.
Once an exception type has been registered it can be raised using
raiseException(String, Long)
or
raiseExceptionMessage(String, Long, String)
to raise an exception
with a non-default message. After an exception has been raised on a process
or a task (either by the process engine or by manually calling
raiseException
), the exception will be resolved as soon as the
state of the process or task becomes anything other than
ProcessSummary.STATE_PAUSED_BY_EXCEPTION
or
TaskSummary.TASK_STATUS_PAUSED_BY_EXCEPTION
respectively.
Methods of service classes can all throw the unchecked exception
ServiceException
if any
system-level error (for example, server failure) occurs, and will in general
throw a checked exception (InvalidXXXException
) when an entity
to be retrieved is inaccessible, instead of returning null
.
Exceptions to this paradigm (including the use of ResultList
as
described below) are noted. All checked exceptions extend
AppianException
.
It may be necessary to retrieve a subset of results as opposed to an entire
collection, and also to sort the subset by some property of the returned
object. "Paging" methods which return a
ResultPage
are provided in certain
instances for this purpose. The ResultPage
will contain the
sorted subset of results
(via Result.getResults()
), and the
total number of items in the available result set
(via ResultPage.getAvailableItems()
).
It may also be necessary to retrieve some results, even if all results
cannot be retrieved (for instance, some of the entities corresponding
to a list of entity IDs may no longer exist). Methods which return a
ResultList
are provided for this
purpose. The Result.getResults()
method in this case will return all results which can be retrieved. In
addition, there will be a list of result codes
(ResultList.getResultCodes()
) that
represent the successful retrieval of an entity, or, if the entity could
not be retrieved, the reason for the failure. See the CODE_XXX
constants in ResultList
for details.
-
Field Summary
Modifier and TypeFieldDescriptionstatic final boolean
static final boolean
static final boolean
static final boolean
static final boolean
static final boolean
Fields inherited from interface com.appiancorp.services.ContextSensitiveService
SET_SERVICE_CONTEXT_METHOD_NAME
-
Method Summary
Modifier and TypeMethodDescriptiongetAllExceptionTypes
(int startIndex_, int batchSize_, Integer sortProperty_, Integer sortOrder_) Get all theProcessExceptionType
objects, paging.getExceptionType
(String exceptionTypeLocalId_) Get theProcessExceptionType
from its unique id.getExceptionTypes
(String[] exceptionTypeLocalIds_) Get theProcessExceptionType
objects from their unique ids.void
raiseException
(String exceptionTypeLocalId_, Long id_) Raise an exception on a task or process.void
raiseExceptionMessage
(String exceptionTypeLocalId_, Long id_, String message_) Raise an exception on a task or process.void
registerExceptionTypesWithNotes
(ProcessExceptionType[] exceptionTypes_, String[] content_) Register exception types, and the note content for those exception types.Methods inherited from interface com.appiancorp.services.ContextSensitiveService
setServiceContext
-
Field Details
-
getExceptionType$UPDATES
static final boolean getExceptionType$UPDATES- See Also:
-
getExceptionTypes$UPDATES
static final boolean getExceptionTypes$UPDATES- See Also:
-
getAllExceptionTypes$UPDATES
static final boolean getAllExceptionTypes$UPDATES- See Also:
-
raiseException$UPDATES
static final boolean raiseException$UPDATES- See Also:
-
raiseExceptionMessage$UPDATES
static final boolean raiseExceptionMessage$UPDATES- See Also:
-
registerExceptionTypesWithNotes$UPDATES
static final boolean registerExceptionTypesWithNotes$UPDATES- See Also:
-
-
Method Details
-
getExceptionType
ProcessExceptionType getExceptionType(String exceptionTypeLocalId_) throws InvalidExceptionTypeException Get theProcessExceptionType
from its unique id.- Parameters:
exceptionTypeLocalId_
- The localId of theProcessExceptionType
to get.- Returns:
- Returns the
ProcessExceptionType
associated with the passed id. - Throws:
InvalidExceptionTypeException
- if noProcessExceptionType
with the passed id exists.ServiceException
- if any system-level error occurs
-
getExceptionTypes
ProcessExceptionType[] getExceptionTypes(String[] exceptionTypeLocalIds_) throws InvalidExceptionTypeException Get theProcessExceptionType
objects from their unique ids.- Parameters:
exceptionTypeLocalIds_
- The localIds of theProcessExceptionType
objects to get.- Returns:
- Returns an array of
ProcessExceptionType
objects associated with the passed ids. - Throws:
InvalidExceptionTypeException
- Thrown if no exception type with the passed id exists.ServiceException
- if any system-level error occurs
-
getAllExceptionTypes
ResultPage getAllExceptionTypes(int startIndex_, int batchSize_, Integer sortProperty_, Integer sortOrder_) Get all theProcessExceptionType
objects, paging.- Parameters:
startIndex_
- The index into the collection of total results at which to start. Negative numbers are treated as zeros.batchSize_
- The number of results to return. useConstants.COUNT_ALL
to return the entire collection, but this is STRONGLY discouraged.sortProperty_
- The property by which the results will be sorted. This will be one of theSORT_BY_XXX
constants inProcessExceptionType
sortOrder_
- The order in which to sort the results. This is one ofConstants.SORT_ORDER_ASCENDING
orConstants.SORT_ORDER_DESCENDING
- Returns:
- Returns a ResultPage of ProcessExceptionType objects.
- Throws:
ServiceException
- if any system-level error occurs
-
raiseException
void raiseException(String exceptionTypeLocalId_, Long id_) throws InvalidExceptionTypeException, IllegalArgumentException, InvalidProcessException, InvalidActivityException, PrivilegeException Raise an exception on a task or process.- Parameters:
exceptionTypeLocalId_
- The localId of the exception type to raise.id_
- The id of the process or task for which the exception should be raised.- Throws:
InvalidExceptionTypeException
- if no exception type with the passed local id exists.IllegalArgumentException
- if the task or process specified byid_
does not existInvalidProcessException
- if no process with the passed id exists.InvalidActivityException
- if no task with the passed id exists.PrivilegeException
- if the user does not have sufficient permissions to execute this method.ServiceException
- if any system-level error occurs
-
raiseExceptionMessage
void raiseExceptionMessage(String exceptionTypeLocalId_, Long id_, String message_) throws InvalidExceptionTypeException, IllegalArgumentException, InvalidProcessException, InvalidActivityException, PrivilegeException Raise an exception on a task or process.- Parameters:
exceptionTypeLocalId_
- The localId of the exception type to raise.id_
- The id of the process or task for which the exception should be raised.message_
- A custom message to show the user- Throws:
InvalidExceptionTypeException
- if no exception type with the passed local id exists.IllegalArgumentException
- if the task or process specified byid_
does not existInvalidProcessException
- if no process with the passed id exists.InvalidActivityException
- if no task with the passed id exists.PrivilegeException
- if the user does not have sufficient permissions to execute this method.ServiceException
- if any system-level error occurs
-
registerExceptionTypesWithNotes
void registerExceptionTypesWithNotes(ProcessExceptionType[] exceptionTypes_, String[] content_) throws PrivilegeException, AppianException Register exception types, and the note content for those exception types. The minimum required fields on the exception type are:localId
. ThenoteId
field will be ignored. Note that there is NO need to separately write the note content to disk usingNotesContentService.createNoteContent(java.lang.String, java.lang.String)
- this will be handled automatically.- Parameters:
exceptionTypes_
- the exception types to be registeredcontent_
- the content of the notes associated with the respective exception types. The length of this array must be the same as the length ofexceptionTypes_
- Throws:
PrivilegeException
- if the user does not have sufficient permissions to execute this method. A user can call this method successfully ifcom.appiancorp.suiteapi.process.security.ProcessPermissions#registerExceptionType
returnstrue
for the user.ServiceException
- if any system-level error occursAppianException
-