| Oracle® Outside In Transformation Server Developer's Guide Release 8.4.1 Part Number E12868-05 |
|
|
View PDF |
| Oracle® Outside In Transformation Server Developer's Guide Release 8.4.1 Part Number E12868-05 |
|
|
View PDF |
A Transformation Engine is a module that is loaded by a Transformation Agent in order to transform a document. To communicate with the Transformation Agent, a Transformation Engine must implement a relatively simple API to support setting of options and executing a transformation.
A transformation engine is not expected to understand SOAP or handle any interprocess communication (except possibly for private reasons). Integration with the larger Transformation Server architecture is the responsibility of the agent that hosts the transformation engine, not the engine itself.
An engine must provide an entry point function named LoadEngine which is used to initialize the engine itself and its communication with the agent. The engine must also implement a handful of functions that are used by the agent to control the process of a transformation. These functions are called the "engine interface." The agent also supplies a set of functions, called the "agent interface," to be used by the engine as needed during a transformation.
The engine and agent present their interfaces to each other through C data structures that contain pointers to functions. With the exception of the LoadEngine entry point, all communication between the engine and the agent is accomplished through the function pointers in these data structures.
This chapter includes the following sections:
The following section describe basic steps in getting started.
Transformation Engines are implemented as loadable modules that can be hosted by any Transformation Agent. Currently, Transformation Engines must implement a C-language API to be successfully integrated into a Transformation Agent. The Transformation Engine interface itself is very simple: it consists of a mapping of the Transform API, and the means to access Transformation Server's IO interface for the inputs and outputs of a transformation.
An engine must provide an entry point function that is called by the Transformation Agent to initialize a transformation. This entry point is used to exchange data structures containing pointers to all of the other API functions on both sides of the interface. One data structure, set by the agent, contains pointers to the functions within the agent that can be called by the engine (the "engine-to-agent" interface). The other data structure contains pointers to the "agent-to-engine" functions, which must be provided by the engine for use by the agent.
A Transformation Agent determines which Transformation Engine to use for a given transformation request by inspecting its configuration information – each supported output format must be mapped to a Transformation Engine. This mapping may be extended with new output formats and/or Transformation Engines at any point in time.
The agent-to-engine interface consists of four functions:
openTransform: Notify an engine to start transforms.
setOption: Set options for the transform.
transform: Perform the transform.
closeTransform: Release resources after a transform.
See Section 6.3, "Engine Interface" for details.
The engine-to-agent interface currently consists of four functions:
openIO: Engine notifies the agent of IO Provider API ioOpen calls.
addToOutputList: Engine notifies the agent of additional files that were created.
setResultMsg: Engine notifies the agent of custom result messages.
logMessage: Engine notifies the agent of messages to be sent to the message logger.
See Section 6.4, "Agent Interface" for details.
The openIO function provides Transformation Engines with a means to access the input and output documents through a BASEIO object (see the description of the IO Provider interface in the next section). Calling the function will cause the Transformation Agent to load an appropriate IO Provider for the IO specification specified. The agent will retrieve a BASEIO printer from the IO Provider, and pass it back to the engine.
Engines are not required to use BASEIO objects for input and output if they are able to open, read, and/or write the specified input and output documents through other means (such as the file system). However, and engine that does access its input and output documents via the BASEIO object will benefit from any IO providers that are installed on the server or provided remotely from the client.
All of the Outside In transformation engines will access input and output documents exclusively through the IO Provider interface.
A Transformation Engine must have access to all of the Transformation Server header files, and it must include TS_ENGINE.H. This file will define the prototype of the entry point function, the structures for the interface, and will pull in any additional header files needed by Transformation Server.
Once an engine has been built, the Transformation Agent must be configured to know where to find the engine. This is done by modifying a configuration file named agent_engine_list.xml. This file contains a list of transformation engines and the formats each one supports.
The following is entry point information.
The LoadEngine function is the entry point through which the Transformation Agent initiates and terminates a conversation with a Transformation Engine. This function is called once immediately after the engine is loaded, and once immediately prior to unloading.
On loading, this function the engine will verify that it supports the specified version of the interface, and if so it will initialize the rest of the EngineInterface structure. On unloading, the engine may perform any cleanup tasks it requires.
Prototype
TSERR LoadEngine( EngineInterface * pEngine, bool bLoading )
Return Values
TSERR_OK: If the function is successful
TSERR_ENGINEVERSION: If the engine does not support the version reported by the Engine structure. In this case, the engine should set its preferred EngineInterface version number in the version field of the EngineInterface structure.
…other TSERR values: As needed.
Parameters
pEngine: This parameter is a pointer to an EngineInterface structure that should be filled in by the transformation engine. It contains pointers that should be set to point to their corresponding functions inside the engine module.
bLoading: This parameter is true if the engine has just been loaded, or false if the engine is about to be unloaded.
The following sections describe the engine interface.
The TransformationEngine structure is defined as follows:
typedef TSERR (*TRANSFORMPROC)(TS_IOSpec *src, TS_IOSpec *sink,
VTLPVOID pEngineData, AgentInterface * agent);
typedef TSERR (*OPENTRANSFORMPROC) (TS_char * outputType,
void * * pEngineData);
typedef void (*CLOSETRANSFORMPROC)(VTLPVOID pEngineData);
typedef struct EngineInterface
{
XSD_unsignedInt version;
OPENTRANSFORMPROC openTransform;
TRANSFORMPROC transform;
SETOPTIONPROC setOption;
CLOSETRANSFORMPROC closeTransform;
} EngineInterface;
version: This specifies the version of the transformation engine API specification to which this engine was written. The format of this number is not currently documented, but later versions are guaranteed to have a higher version number than earlier versions. Developers should set this value to kTransformEngineInterfaceVersion, which is the current version as defined by the header files in use.
openTransform: This is a pointer to the transformation engine's openTransform function
transform: This is a pointer to the transformation engine's transform function
setOption: This is a pointer to the transformation engine's setOption function
closeTransform: This is a pointer to the transformation engine's closeTransform function
The openTransform function is the entry point through which the Transformation Agent initiates a conversation with a Transformation Engine. This function is called each time a new transformation operation is about to begin.
Prototype
TSERR openTransform(TS_char * outputFormat, void **
pEngineData);
Return Values
TSERR_OK: If the function is successful
TSERR_FORMATNOTSUPPORTED: If the engine does not support the specified output format.:
…other TSERR values: as needed
Parameters
outputFormat: This identifies the selected output format for the transformation. This is a null-terminated string, composed of UTF-8 encoded Unicode characters.
pEngineData: The value pointed to by pEngineData should be set to a value for the private use of the engine. This value will be passed back to the engine on subsequent interface calls. Typically, an engine would set *pEngineData to point to some data structure that it uses for tracking data specific to the current transformation.
This function sets options for transformations.
Prototype
TSERR setOption(TS_char * name, void * data, XSD_unsignedInt
type, void * engineData);
In practice, it is possible that setOption will be called more than once for the same option. By definition, the last value set for an option should be considered its "true" value.
Return Value
Returns TSERR_OK if successful, or an error if the option could not be set.
Parameters
name: The name of the option being set
data: This is a void pointer to the value associated with the option being set.
type: This identifies the type of the data pointed to by the value pointer. Possible values are any of the following:
XSD_boolean_type
XSD_string_type
XSD_float_type
XSD_double_type
XSD_int_type
XSD_short_type
XSD_byte_type
XSD_unsignedInt_type
XSD_unsignedShort_type
XSD_unsignedByte_type
TS_CharacterSetEnum_type
TS_stringData_type
TS_IOSpec_type
TS_binaryData_type
OIT_AltLink_type
OIT_CellHeadings_type
OIT_CharMappingEnum_type
OIT_CharacterAttributes_type
OIT_CharacterByteOrderEnum_type
OIT_ComplianceEnum_type
OIT_DatabaseFitToPageEnum_type
OIT_DefaultFont_type
OIT_DefaultInputCharSetEnum_type
OIT_DefaultMargins_type
OIT_DefaultPageUnitsEnum_type
OIT_DocumentMemoryModeEnum_type
OIT_EmailHeaderOutputEnum_type
OIT_ExtractEmbeddedFilesEnum_type
OIT_FlavorEnum_type
OIT_FallbackFormatEnum_type
OIT_FontFlags_type
OIT_GraphicCroppingEnum_type
OIT_GraphicSizeMethodEnum_type
OIT_GraphicTypeEnum_type
OIT_GraphicWatermarkScaleTypeEnum_type
OIT_GridAdvanceEnum_type
OIT_MimeHeaderOutputEnum_type (deprecated)
OIT_ParagraphAttributes_type
OIT_ReorderMethodEnum_type
OIT_SearchMLFlags_type
OIT_SearchMLUnmappedTextEnum_type
OIT_SpreadsheetFitToPageEnum_type
OIT_SpreadsheetPageDirectionEnum_type
OIT_SpreadsheetShowBorderEnum_type
OIT_TiffOptions_type
OIT_WatermarkPositionEnum_type
OIT_WatermarkScalingEnum_type
OIT_XmlDefinitionMethodEnum_type
engineData: This is the engineData value supplied by the transformation engine during the OpenTransform function.
This is the function that actually accomplishes a transformation.
Prototype
TSERR transform(struct TS_IOSpec *src, struct TS_IOSpec *sink,
void * engineData, AgentInterface * agent);
Return Value
Returns TSERR_OK if successful, or an error if the transformation failed.
Parameters
src: This is the IO specification of the input document for the transformation.
sink: IO specification for the output of the transformation
engineData: This is the engineData value supplied by the transformation engine during the OpenTransform function.
agent: The pAgent parameter is a pointer to an AgentInterface structure, through which the engine can communicate back to the Agent.
This function is called by the transformation agent to notify the transformation engine that the transformation represented by hTransform may be disposed.
void closeTransform(void * hTransform);
Parameters
hTransform: This is the identifier supplied by the transformation engine as the return value of the OpenTransform function.
The following information pertains to agent interface features.
The AgentInterface structure has the following definition:
typedef TSERR (*OPENIOSPECPROC)(TS_IOSpec * spec,
XSD_unsignedInt flags, BASEIO ** ppDoc, struct
AgentInterface * agent );
typedef TSERR (*ADDTOOUTPUTLISTPROC)(TS_char * spec,
TS_CharacterSetEnum charSet, TS_char * specType,
AgentInterface * agent );
typedef TSERR (*SETRESULTMSGPROC)(TS_char * spec,
TS_CharacterSetEnum charSet, struct AgentInterface * agent
);
typedef TSERR (*LOGMESSAGEPROC)(TS_char * msg,
TS_CharacterSetEnum charSet, TS_MessageTypeEnum type, struct
AgentInterface * agent );
typedef struct AgentInterface
{
XSD_unsignedInt version
OPENIOSPECPROC openIO;
ADDTOOUTPUTLISTPROC addToOutputList;
SETRESULTMSGPROC setResultMsg;
LOGMESSAGEPROC logMessage;
} AgentInterface;
version: This specifies the version of the transformation engine API specification in use by the transformation agent host. This is the same value as described for the EngineInterface version field.
openIO: Points to the agent's openIO function.
addToOutputList: Points to the agent's addToOutputList function
setResultMsg: Points to the agent's setResultMsg function
logMessage: Points to the agent's logMessage function
This function is called by the engine to open an "IO object", which is a source of input or destination of output. Access to the IO object is provided through a BASEIO structure.
TSERR openIO(TS_IOSpec * spec, XSD_unsignedInt flags, BASEIO **
ppDoc, AgentInterface * agent)
Parameters
spec: A pointer to a TS_IOSpec structure that specifies a document to be opened for reading or writing
flags: One or more flags that indicate how the document is to be opened. Possible values are:
IOOPEN_READ: The document is being opened for reading
IOOPEN_WRITE: The document is being opened for writing
IOOPEN_CREATE: The document is being created. If a document of the same name exists, it will be replaced by the new document. Any documents opened with the IOOPEN_CREATE flag will automatically be added to the list of output documents reported with the results of the transformation, unless IOOPEN_PRIVATE is also specified.
IOOPEN_PRIVATE: When use with IOOPEN_CREATE, prevents the file from being included in the list of output files for the current transformation.
ppDoc: If the openIO function is successful, this variable will be set to point to a BASEIO structure that will provide access to the document that was opened.
agent: The pointer to the AgentInterface structure that was passed as a parameter to the transform function
Return Values
TSERR_OK if the operation was successful, or an error value if it was not.
This function is called by the engine when creating output documents through some means other than the openIO function. Documents specified through this function will be included in the list of output documents that is reported to the originator of the transformation request.
Any documents created via the agent's openIO function are automatically added to the output list; for those documents there is no need to call this function.
Prototype
TSERR addToOutputList(TS_char * spec, TS_charsetEnum charSet,
TS_char * specType, AgentInterface * agent )
Return Values
TSERR_OK if the operation was successful, or an error value if it was not.
Parameters
spec: The specification of the output document
charSet: The character set used in the spec string
specType: The type of specification (for example, "path", "URL", etc.)
agent: The pointer to the AgentInterface structure that was passed as a parameter to the transform function
This function is called by the engine to specify a result string for the transformation operation. Use of this function is optional.
TSERR setResultMsg(TS_char * msg, TS_charsetEnum charSet,
AgentInterface * agent )
Return Values
TSERR_OK if the operation was successful, or an error value if it was not.
Parameters
msg: A string containing the result message
charSet: The character set used in the message string
agent: The pointer to the AgentInterface structure that was passed as a parameter to the transform function
This function is called by the engine for diagnostic purposes, to add a string to Transformation Server's error log.
TSERR logMessage(TS_char * msg, TS_CharacterSetEnum charSet,
TS_MessageTypeEnum type, struct AgentInterface * agent );
Return Values
TSERR_OK if the operation was successful, or an error value if it was not.
Parameters
msg: A string containing the error message
charSet: The character set used in the message string
type: One of the following:
msgError: The message describes an error
msgInfo: The message is for informational purposes
msgStatus: The message provides ongoing status information about the current transformation
agent: The pointer to the AgentInterface structure that was passed as a parameter to the transform function
|
 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|