SPE API

The SPE API functions are organized here by category. For more information, see the Javadoc files.

Using the SPE public interface API

The SPE public interface API performs the central SPE functions (enveloping, de-enveloping, transformation, and related capabilities) as a set of API calls. This functionality allows you to easily plug these capabilities into other applications.

To perform these SPE functions, include the following steps in your Java™ program:

Initialize SPE and set any special options.
Perform any actions such as enveloping or de-enveloping.
Commit or roll back any database updates.
Terminate the SPE program.

Methods from the SPE class are used to perform these tasks. The following sections give a brief description of how to do each of these steps and the methods most commonly used. For more detailed descriptions, see the Javadoc files.

Security

When the SPE API is called, it runs under the permission that is established by the caller. The caller has the responsibility to lower the risk of Standards Processing Engine accessing unwanted directories. To lower the risk, run under appropriate permissions and control the paths that are passed to SPE applications.

Initializing SPE

To initialize SPE, do the following steps:

Create an SPE instance by calling the SPE() constructor. For example:
```
SPE myspe = new SPE();
```
Register the classes to use for the Storage, Persistence, and Event providers.
See SPE SPE Event API for more information about using the default SPE provider or writing a custom Event provider to handle SPE events. See Storage API for more information about using the Storage providers that are included with SPE.
Note: Although it is possible to create custom Storage and Persistence provider classes, the use of the included Storage and Persistence providers is recommended.

To customize the way SPE handles input or output documents, database access, and event information, you can specify other providers. Use the registerStorageProvider, the registerProvider, and the registerProviderGroup methods to specify class names for your providers.
Set any necessary provider options, such as database URL, by using the configureProvider and the configureProviderGroup methods. Other SPE properties can be set by using the setSPEProperties method or set in the customer_overrides.properties file.

Perform actions

The SPE API allows you to perform various actions, such as:

Initialize the SPE database tables during first-time setup
Import, export, migrate, and delete trading partner information
De-envelope EDI data
Encode and envelope EDI data
Use a map to transform data from one format to another
Validate data
Perform miscellaneous EDI functions, including identifying the standard type or getting a report of pending acknowledgements

Output

These functions return a Response object to the caller. The Response object includes the following outputs:

Output documents, returned as a list of IResource objects
Type information about each document, such as whether they are final or intermediate documents, and whether they contain acknowledgements.
Correlation and process parameter information that is generated by the function
Report, status, and log information

Initialize the SPE database tables

initialLoad: Calls each of the registered persistence providers to create the database tables that they need, and does an initial load of the data.

Trading partner import and export

importResources: Imports trading partner information into the database. Different argument types allow you to import from either an XML-formatted SPE import file, or to import maps and schemas directly.

exportResources: Exports trading partner information from the database to an XML-formatted SPE export file.
deleteResources: Deletes trading partner information from the database.

Enveloping and De-enveloping methods

deenvelope: De-envelopes documents from an EDI interchange format, generates appropriate acknowledgments, and optionally transforms the documents.

encode: Looks up trading partner information that is associated with a document to prepare it for enveloping. If the enveloping mode is immediate, the encode method also envelopes the documents.
envelope: Envelopes one or more documents into a format such as EDI interchange.

Importance of committing before a rollback:

If you roll back a transaction due to the return of an ERROR status on an enveloping or de-enveloping process, commit the transaction. The commit does not negatively affect your processes. It also prevents the invalid state that might occur if other threads successfully increment the same control number counter before the original transaction is rolled back.

Validation and Transformation methods

transform: Transforms a document from one format to another using a map. Map types include WebSphere® Transformation Extender maps, Sterling B2B Integrator maps, and XSLT scripts.

validate: Validates a document to determine whether it conforms to an XML schema.

Methods used to perform other tasks

checkPendingAckStatus: Gets a status report of all acknowledgments that match a specified status.

documentExtraction: Splits individual documents out of a batch file to make each one a separate document.
identifyStandardTypes: Checks documents to see what standard types are included. An input document might contain a batch of different standard types and interchanges, and this method finds the starting and ending offset for each.

Transaction handling methods

The following methods are used to control transaction handling, regardless of whether the changes are committed or rolled back.

beginTransaction: Signals the beginning of a transaction. It is typically called before the calls to perform tasks, such as importing trading partner data or enveloping, de-enveloping, or transforming documents.

commit: Signals the end of a transaction, and that the database changes should be committed. It is normally called after a task returns successfully.
Even if the task reports errors, commit the changes. For example, if the de-enveloping process reports errors in the EDI data, commit the database changes so that state changes such as control number sequence information are recorded.
rollback: Rolls back (discards) the database changes since beginTransaction was called. It is normally called if tasks such as importing trading partner information, or enveloping, de-enveloping, or transforming documents have an unexpected error.