Exception handling is the process of responding to the occurrence, during computation, of exceptions – anomalous or exceptional situations requiring special processing – often changing the normal flow of program execution.
With Open-Xchange Server v6.22 the exception handling has been heavily simplified. There is only a single class named OXException. As prerequisite for remodeling the exception handling, existing error code notations – e.g. APP-0015 – and uniquely identifying exception ID – exceptionID=-1272648052-227787 – need to be maintained. Newly introduced classes OXExceptionCode and OXExceptionFactory now replace formerly used classes Code, ErrorMessage, and ExceptionFactory respectively.
Moreover the new exception framework distinguishes between log and display messages. The log messages technically describe the occurred error with optional debug information (e.g. user, context, …). Whereby the display message is intended as a short, understandable and translatable message for the Open-Xchange user. The display messages are provided as public constants by a simple class implementing com.openexchange.i18n.LocalizableStrings interface.
These simplifications to exception handling imply severe impact on existing OX6-compliant source code that need special developer’s intention:
For developing OSGi bundles for Open-Xchange Server the helper class HousekeepingActivator is recommended. This subclass of OSGi’s BundleActivator interface offers many utility methods to register new services or to track needed ones.
Both, ServiceRegistrations and ServiceTrackers, are internally stored and automatically release if the stop() method is invoked. Thus it is ensured that any opened OSGi resource is orderly closed on bundle stop.
To do so, you need to provide an implementation of the AJAXActionFactory interface which delivers an AJAXActionService implementation for every ?action=someAction type parameter in the HTTP API for your module. The AJAXActionFactory can be registered in the OSGi container by having your Activator subclass ModuleActivator and using its #registerModule method.
The meat of your HTTP API implementation will usually reside in the AJAXActionService implementations. They are expected to return an AJAXRequestResult for a given AJAXRequestData (which typically wraps an HTTP request, but could just as well emanate from a „multiple“ batch request or another interface). The AJAXRequestData provides access to the actions parameters and body data, already pre-parsed as JSON data, if that was possible.
AJAXRequestResults consist of the payload and the format that payload is provided in by the AJAXActionService implementation. This is used to automatically turn a given result type (say „contact“, which would be one or many contact objects) into, say a „vcard“, depending on what the client requested as desired format. Typically the response will be in JSON format, though.
Known types you can stick into an AJAXRequestResponse are:
For simple use cases that is enough. If you work with highly structured data (like OXs main data types contacts, appointments, tasks, files, mails) and introduce your own complex object type ( for the sake of argument say: an Order in a logistics application), it’d be best to introduce your own format („order“, or „ox:order“ with your own prefix instead of „ox“. Just pick one) and (at minimum) an implementation of ResultConverter that knows how to turn whatever object you supply as an „order“ into „json“. That way you can later easily add different output options for different clients (e.g. „csv“ to print a list of orders in a spreadsheet friendly csv file).