C
Descriptive Matrix

This appendix describes the descriptive matrix of the schemas and adaptors supplied by Oracle Dynamic Services.

C.1 Syntax of the Service Descriptor Schema

At the top level, a service descriptor schema contains the data shown in Table C-1. Table Table C-2 through Table C-4 show the descriptive matrix for the classification, contact, and organization schemas. Required data is designated by bold element names. Element names are indented to show the relationship and hierarchy of elements. A service provider will define a service by writing an XML document that complies with the XML schema file sd.xsd and other auxiliary documents such as the classification, organization, and contact XML documents. See Example 6-11 through Example 6-15 to view the contents of sample service header and service body sections of a service descriptor schema.

Table C-1 Descriptive Matrix of the Service Descriptor Schema

Element Name						Description
SERVICE_DESCRIPTOR						Required element. The root element in the service descriptor document.
	SERVICE_HEADER					Required element. The service header section. Contains high-level descriptions of the service.
		NAMING				Required element. The naming section. Contains a globally unique identifier ID, as well as NAME and DESCRIPTION elements describing what the service does.
			ID			Required element. An identifier uniquely identifies the service and must be a uniform resource name (URN).
			NAME			Required element. The name of the service.
			DESCRIPTION			Required element. The description of the service.
		PACKAGE				Required element. The package section. Contains version specifications and pointers to where the service update is to be performed.
			VERSION			Required element. The version number of the service definition package.
			RELEASEDATE			Required element. The release date of the service definition package.
			UPDATEURL			Optional element. The URL to obtain the latest version of the service definition package. In general, a service should contain an update URL. Note: However, for services created by an administrator, this parameter is meant to be used locally and UPDATEURL is not applicable (not used currently).
			BINARY_RESOURCES			Optional element. The binary resources section. For advanced usage, such as specifying locations for Java class files or stylesheets for custom services and adaptors, as well as names of resource bundles.
				JAR_POINTER		Optional element. The URL of the jar file containing service-specific Java classes and resources within the service definition zip file.
				EXCEPTIONS		Optional element. The exceptions section. Contains the specification for the resource bundle for custom exceptions.
					EXCEPTION_MSG_BUNDLE	Optional element. The specification for the custom exceptions that rely on the custom resource bundle.
		DEPLOYMENT				Required element. The deployment section. Contains a set of deployment properties from the service provider to aid the service administrator during service registration.
			CLASSIFICATION			Required element. An xlink to the classification XML document. Service providers can provide suggestions while a service administrator will decide the classification of the service. The XML file should comply with sd_classification.xsd. See Table C-2 for a description of the classification schema.
			CACHING			Required element. The caching section. Contains recommended caching parameter values.
				MAX_AGE		Required element. The duration that a cache entry is valid for, in seconds. If the value is 0, it means the entry should not be cached. The default value is 0.
				SESSION_PRIVATE		Required element. A value of TRUE means that the scope of the cache entry is within the service engine user session. The default value is FALSE.
				USE_PROTOCOL		Required element. A value of TRUE means that the protocol caching parameters will override MAX_AGE. The default value is FALSE.
		PROVIDER				Required element. The service provider section. Contains information about the service provider including the provider's company name, copyright information, company URL, contacts for support, and URLs for logos.
			ORGANIZATION			Required element. An xlink to the organization XML document. Provides generic information about the service provider. The xml file should comply with sd_organization.xsd. See Table C-4 for a description of the organization schema.
			CONTACTS			Required element. The contacts section. Contains detailed support contacts for this service.
				CONTACT		Required repeating element. An xlink to the contact XML document. Provides information to contact a person for any issues related to the service. The xml file should comply with sd_contact.xsd. See Table C-3 for a description of the contact schema.
		INTERFACE				Required element. The service interface specification. Contains the definition of an interface characterized by the schema specifications of its input, output, and exceptions.
			NAME			Required element. The name of the interface template.
			INPUT_SCHEMA			Required element. An xlink to the request XML document. The URL to the request definition XML schema document, or the DTD defining the XML service request syntax.
			OUTPUT_SCHEMA			Required element. An xlink to the response XML document. The URL to the response definition XML schema document, or the DTD defining the XML service response syntax.
	SERVICE_BODY					Required element. The service body section. Contains detailed descriptions and information used by the Dynamic Services engine at execution time. Information is sectioned into specifications (including adaptors) for input, protocol, execution, and output.
		INPUT				Optional element. The input section. Contains the details for preprocessing the XML request from the service consumer application and includes the following sections: namespaces, alias directives, input adaptor, and rendering directives.
			NAMESPACES			Optional element. The namespaces section. Declares any namespaces and their prefixes that can be used in the aliases section to build the XPaths pointing to where the data is located.
				NAMESPACE		Required repeating element. A single entry of a namespace definition.
				PREFIX		Required element. The namespace prefix.
				VALUE		Required element. The namespace value.
			ALIASES			Optional element. The aliases section. Used by service providers to specify additional directives for the purpose of creating aliases. Aliases are used to create a map that can translate the parameters embedded in the XML document to actual parameters needed by the adaptor (for example, the protocol adaptor).
				ALIAS		Required repeating element. A single entry of an alias definition.
					NAME	Required element. The alias name.
					VALUE	Required element. The alias value. Can be specified as an XPath or as a service consumer application profile property and optionally its modifier. The XPath is used at run-time to extract either the value of the node pointed to by the XPath, or the XML fragment (for which this node is the root) from the service request.
			RENDERERS			Optional element. The renderers section. Contains additional rendering directives. The service provider can optionally supply some form of schema mapping specifications, such as an XSL transformation, that could map the input XML schema to a presentation form such as HTML or Wireless Markup Language (WML). Thus, the service consumer application can provide to its clients a way to enter service requests, for applications that have an HTML or WML interface.
				RENDERER		Optional element. A single entry of the renderers definition.
					TYPE	Optional element. The type of rendering directive, such as the request XML document or the type of input transformation, or both.
					STYLESHEET	Optional element. An xlink to the request XML document or the schema mapping specification XSL transformation, or both. The URL to the request XML document or the XSL transformation mapping the input XML schema to a presentation form, or both.
			ADAPTOR			Optional element. The input adaptor section. Specifies, optionally, an adaptor that further processes the service request before sending it to the service provider. A packaged adaptor is the XSLT input adaptor.
				NAME		Optional element. The fully qualified name of the class implementing the oracle.ds.engine.InputAdaptor Java interface that handles the processing.
				PARAMETERS		Optional element. The parameters specification. The service provider can optionally specify adaptor-specific parameters that are validated at service registration time and interpreted at runtime by the adaptor. These parameters must be in XML syntax. See Table C-5 for a description of the input adaptors parameters specification.
		PROTOCOL				Optional element. The protocol section. Contains the details for submitting a request to the service provider. Identifies the way that a service engine accesses the underlying service.
			ADAPTOR			Optional element. The protocol adaptor section. Specifies, optionally, an adaptor that transforms the standard service request into the input needed by the underlying service, using the underlying protocol.
				NAME		Required element. The fully qualified name of the class implementing the oracle.ds.engine.ProtocolAdaptor interface that handles the communication to the underlying service. Packaged protocol adaptors support the HTTP, HTTPS, SMTP, or JDBC protocols.
				DRIVER		Required element. The driver specification. Ensures that a certain class in the classpath for the adaptor to function properly.
				PARAMETERS		Optional element. The parameters specification. The service provider can optionally specify adaptor-specific parameters that are validated at service registration time and interpreted at runtime by the adaptor. These parameters must be in XML syntax. See Table C-7, Table C-8, and Table C-9 for a description of the HTTP, JDBC, and SMTP protocol adaptors parameters specifications.
		EXECUTION				Optional element. The execution section. Identifies the way in which the service must be executed. It takes the request XML and returns the response from the underlying service provider.
			ADAPTOR			Optional element. The execution adaptor section. Specifies, optionally, an adaptor that executes a service request in a particular flow or order.
				NAME		Optional element. The fully qualified name of the class implementing the oracle.ds.engine.ExecutionAdaptor Java interface that performs the execution. Packaged adaptors are compound, failover, and conditional service execution adaptors.
				PARAMETERS		Optional element. The parameters specification. The service provider can optionally specify adaptor-specific parameters that are validated at service registration time and interpreted at runtime by the adaptor. These parameters must be in XML syntax. See Table C-10 and Table C-11 for a description of the compound and conditional execution adaptors parameters specifications.
		OUTPUT				Optional element. The output section. Specifies the list of necessary as well as optional processing to produce the service response to the service consumer application. Includes the output adaptor and rendering directives sections.
			RENDERERS			Optional element. The renderers section. Contains additional rendering directives. The service provider can optionally supply some form of schema mapping specifications, such as an XSL transformation, that could map this response XML to other forms, such as HTML or WML. Thus, the service consumer application can provide to its clients a way to produce service responses, for applications that have an HTML or WML interface.
				RENDERER		Optional element. A single entry of the renderers definition.
					TYPE	Optional element. The type of rendering directive, such as the response XML document or the type of output transformation, or both.
					STYLESHEET	Optional element. An xlink to the response XML document or the schema mapping specification XSL transformation, or both. The URL to the response XML document or the XSL transformation mapping the output XML schema to a presentation form, or both.
			ADAPTOR			Optional element. The output adaptor section. Specifies an output adaptor to be used to transform the output returned by the execution adaptor into an XML document compliant with the output XML schema specified in the service interface. The output name is a fully qualified name of the class implementing the oracle.ds.engine.OutputAdaptor interface that handles the transformation. A packaged adaptor is the XSLT output adaptor.
				NAME		Optional element. The fully qualified name of the class implementing the oracle.ds.engine.OutputAdaptor Java interface that handles the transformation.
				PARAMETERS		Optional element. The parameters specification. The service provider can optionally specify adaptor-specific parameters that are validated at service registration time and interpreted at runtime by the adaptor. These parameters must be in XML syntax. See Table C-5 for a description of the output adaptors parameters specification.

At the next level, a Classification schema contains the data shown in Table C-2. Required data is designated by bold element names. Element names are indented to show the relationship and hierarchy of elements. See Example 6-5 to view the contents of a classification schema.

Table C-2 Descriptive Matrix of the Classification Schema

Element Name		Description
CLASSIFICATION		Required element. The classification information from the service provider to assist the service administrator during registration.
	CATEGORY	Required element. The hierarchical categories specified using the substring of the Distinguished Name (DN) specified in the RFC2253 specification (`http://www.ietf.org/`).
	KEYWORDS	Required element. The keywords, separated by commas.

At the next level, a Contact schema contains the data shown in Table C-3. Required data is designated by bold element names. Element names are indented to show the relationship and hierarchy of elements. See Example 6-4 to view the contents of a contact schema.

Table C-3 Descriptive Matrix of the Contact Schema

Element Name		Description
CONTACT		Required element. The contact information from the service provider.
	NAME	Required element. The name of the contact.
	EMAIL	Required element. The electronic mail address.
	PHONE	Required element. The phone number.
	FAX	Required element. The FAX number. The default is " ".
	PAGER	Required element. The pager number. The default is " ".
	MOBILE	Required element. The mobile number. The default is " ".

At the next level, an Organization schema contains the data shown in Table C-4. Required data is designated by bold element names. Element names are indented to show the relationship and hierarchy of elements. See Example 6-3 to view the contents of an organization schema.

Table C-4 Descriptive Matrix of the Organization Schema

Element Name		Description
ORGANIZATION		Required element. The company information from the service provider.
	NAME	Required element. The service provider's company name.
	COPYRIGHT	Required element. The copyright information for the company.
	URL	Required element. The URL for the company.
	LOGOURL	Required element. The URL for the company's logo.

C.2 Syntax of the Parameters Section for the Packaged Adaptors

Table C-5 through Table C-12 show the descriptive matrix for the parameters section of each type of adaptor schema supplied by Oracle Dynamic Services.

C.2.1 oracle.ds.engine.ioa.DSXSLTInputAdaptor

An Input Adaptor schema contains the data shown in Table C-5. Required data is designated by bold element names. Element names are indented to show the relationship and hierarchy of elements. See Example 6-13 to view the contents of the input adaptor schema contained within the service body description.

Table C-5 Descriptive Matrix of the Input Adaptor Parameters

Element Name		Description
XSLT_IA_PARAMS		Optional element. The parameters section of the input adaptor supplied by Oracle Dynamic Services.
	XSLT	Optional element. The XSL stylesheet used by the input adaptor. Takes in two attributes: the isSchemaCompliant attribute specifies whether or not the XML request schema is compliant after applying the XSL stylesheet, and the applyWithServiceDescriptor attribute specifies the names of additional service descriptors to bring in before applying the stylesheet.
	isSchemaCompliant	Attribute. Specifies whether or not the XML request schema is compliant after applying the XSL stylesheet. The data type is Boolean. The default value is false. This attribute is currently not in use.
	applyWithServiceDescriptor	Optional attribute. Specifies the names of additional service descriptors to bring in before applying the stylesheet. The data type is string.

C.2.2 oracle.ds.engine.ioa.DSXSLTOutputAdaptor

An Output Adaptor schema contains the data shown in Table C-6. Required data is designated by bold element names. Element names are indented to show the relationship and hierarchy of elements. See Example 6-15 to view the contents of the output adaptor schema contained within the service body description.

Table C-6 Descriptive Matrix of the Output Adaptor Parameters

Element Name		Description
XSLT_OA_PARAMS		Optional element. The parameters section of the output adaptor supplied by Oracle Dynamic Services.
	XSLT	Optional element. The XSL stylesheet used by the output adaptor. Takes in two attributes: the isSchemaCompliant attribute specifies whether or not the XML response schema is compliant after applying the XSL stylesheet, and the applyWithServiceDescriptor attribute specifies the names of additional service descriptors to bring in before applying the stylesheet.
	isSchemaCompliant	Attribute. Specifies whether or not the XML response schema is compliant after applying the XSL stylesheet. The data type is Boolean. The default value is false. This attribute is currently not in use.
	applyWithServiceDescriptor	Optional attribute. Specifies the names of additional service descriptors to bring in before applying the stylesheet. The data type is string.

C.2.3 oracle.ds.engine.pa.DSHTTPProtocolAdaptor

An HTTP Protocol Adaptor schema contains the data shown in Table C-7. Required data is designated by bold element names. Element names are indented to show the relationship and hierarchy of elements. See Example 6-27 to view the contents of the HTTP protocol adaptor parameters section contained within the service body description.

Table C-7 Descriptive Matrix of the HTTP Protocol Adaptor Parameters

Element Name				Description
HTTP_PA_PARAMS				Optional element. The section for the HTTP Protocol Adaptor parameters.
	Method			Required element. The method used for the HTTP request. Must be one of three options: GET, POST, or HEAD.
	URL			Required element. The URL to be contacted.
	RequestHeaders			Optional element. Setting HTTP request headers in the request. Contains the definition of additional HTTP request headers that the user wants to define.
		RequestHeader		Required repeating element. The request header. Used to set the HTTP request header in the request. It is specified as a name attribute and element value of this element. Any number of request headers can be specified.
		name		Attribute. The name of the request header. The data type is string.
	QueryStringParameters			Optional element. The definition of the query string used for complex GET or POST requests.
		QueryStringParameter		Required repeating element. The query string parameter. There can be one or more parameters for the HTTP query string. Each of these elements defines one parameter. It is specified as a "name" attribute and element value of this element. Any number of query string parameters can be specified.
		name		Attribute. The name of the query string parameter. The data type is string.
	Authorization			Optional element. Used for some secured Web sites that require the user's login name and password. It contains either an encoded string element or a credential element.
	type			Attribute. The type of authorization. The value is fixed to the value Basic.
		EncodedString		Required element. The encoded string that contains the user's login name and password. The data type is string.
		Credential		Required element. The credential section. Contains the user name and password elements.
			Username	Required element. The user's login name. The data type is string.
			Password	Required element. The user's login password. The data type is string.

C.2.4 oracle.ds.engine.pa.DSJDBCProtocolAdaptor

A JDBC Protocol Adaptor schema contains the data shown in Table C-8. Required data is designated by bold element names. Element names are indented to show the relationship and hierarchy of elements. See Example 6-29 to view the contents of the JDBC protocol adaptor parameters section contained within the service body description.

Table C-8 Descriptive Matrix of the JDBC Protocol Adaptor Parameters

Element Name				Description
JDBC_PA_PARAMS				Optional element. The section for the JDBC Protocol Adaptor parameters.
	Connectiondefs			Required element. The section for connection definitions.
		Connection		Required repeating element. The connection section. Specifies the database connection parameters.
			Username	Required element. The database user name. The data type is string.
			Password	Required element. The database password. The data type is string.
			dburl	Required element. The database URL. The data type is string.
			driver	Optional element. The name of the Oracle JDBC driver. The data type is string.
			autocommit	Required element. The automatic commit parameter value. The data type is Boolean. The default is TRUE to automatically commit any updates.
	Page			Required element. The name of the connection page.
		Query		Required element. The query string.

C.2.5 oracle.ds.engine.pa.DSSMTPProtocolAdaptor

An SMTP Protocol Adaptor schema contains the data shown in Table C-9. Required data is designated by bold element names. Element names are indented to show the relationship and hierarchy of elements. See Example 6-30 to view the contents of the SMTP protocol adaptor parameters section contained within the service body description.

Table C-9 Descriptive Matrix of the SMTP Protocol Adaptor Parameters

Element Name			Description
SMTP_PA_PARAMS			Optional element. The section for the SMTP Protocol Adaptor parameters.
	Host		Required element. The SMTP host name. The data type is string.
	Port		Required element. The SMTP port number. The data type is positive integer.
	From		Required element. From whom the mail was sent. The data type is string.
	To		Required element. To whom the mail is to be sent. The data type is string.
	cc		Optional element. To whom else should receive a copy of the mail. The data type is string.
	bcc		Optional element. To whom else should receive a copy of the mail, but that is unseen by anyone else who receives a copy. The data type is string.
	Subject		Required element. The subject line of the mail. The data type is string.
	MsgHeaders		Optional element. The message header section.
		MsgHeader	Required repeating element. The header of the mail message. It is specified as a name attribute and element value of this element.
		name	Attribute. The name of the message header. The data type is string.
	MsgBody		Required element. The body of the mail message.

C.2.6 oracle.ds.engine.ea.compound.DSCompoundServiceExecutionAdaptor

A Compound Execution Adaptor schema contains the data shown in Table C-10. Required data is designated by bold element names. Element names are indented to show the relationship and hierarchy of elements. See Example 6-32 through Example 6-41 to view the contents of the compound execution adaptor parameters sections contained within the service body description that are described in Table C-10.

Table C-10 Descriptive Matrix of the Compound Execution Adaptor Parameters

Element Name								Description
COMPOUND_EA_PARAMS								Optional element. The section for the compound execution adaptor parameters. Contains the specification that encapsulates the execution of a multitude of services, combining them into a directed graph of service executions.
	Modules							Required element. The modules section.
		Module						Required element. A single entry of a module. The name attribute specifies the name of the module.
		Name						Attribute. The module name. The data type is string.
			Class					Required element. The class type. One of four classes of compound service execution modules: service execution, message transformer, message splitter, and message merger.
			Properties					Required element. Properties needed by each module.
				Message Splitter Properties: choice of MultipleTransformations or SingleTransformation
					MultipleTransformations			Required element. The multiple transformations module. This module splits a single message into multiple messages, working with a specified list of XSLTs. With each XSLT, an index is also specified to order the list of service messages that result in the one-by-one application of the XSLTs. Each service message has a valid index that is sequential, starting from 0.
						XSLT		Required repeating element. The specified list of XSLTs. This list corresponds to a list of transformations to the original service message, which then produces a list of resulting messages.
						index		Attribute. The XSLT index number. The data type is a non-negative integer.
					SingleTransformation			Required element. The single transformation module. This module splits a single message into multiple messages. The specified XSLT transforms the starting service message into a list of service messages, each with a valid index that is sequential, starting from 0.
						XSLT		Required element. The specified XSLT.
				Service Execution Properties: choice of executeSingleRequest or executeAllRequests
					executeSingleRequest			Required element. The execute single request option. This compound service execution takes in a message index number as an attribute (a request event can contain a list of requests) and takes the ID of the service to be executed, as an element value. Only one execution is performed using one selected request message. The service specified by the ID with that request is executed.
					index			Attribute. The message index number. The data type is a non-negative integer.
					executeAllRequests			Required element. The execute-all-requests option. This compound service execution takes the ID of the service as an element value and executes the service with all the request messages from the request event, generating response messages to create a response event. The data type is string.
				Message Merger Properties
					XSLT			Required element. The message merger XSLT. The data type is string.
				Message Transformer Properties
					XSLT			Required element. The message transformer XSLT. The data type is string.
				Execution Flow Definition Using a Dependency Matrix
					Graph			Required element. The dependency matrix. Contains the definition of the execution flow among a set of modules using a dependency matrix. In the dependency matrix, each module is specified by a row name and each module is also ordered by column. A dependency is represented by a column value of 1, while a value of 0 means there is no dependency.
						row		Required repeating element. The row element. The name attribute specifies the row name.
						name		Attribute. The name of the row. The data type is string.
							column	Required repeating element. The dependency column value for each module. A value of 1 means that for the specified row, there is a dependency upon those modules representing those columns. A value of 0 means there is no dependency. The data type is a non-negative integer.

C.2.7 oracle.ds.engine.ea.DSConditionalExecutionAdaptor

A Conditional Execution Adaptor schema contains the data shown in Table C-11. Required data is designated by bold element names. Element names are indented to show the relationship and hierarchy of elements. See Example 6-42 to view the contents of a sample conditional execution adaptor parameters section contained within the service body description.

Table C-11 Descriptive Matrix of the Conditional Execution Adaptor Parameters

Element Name						Description
CONDITIONAL_EA_PARAMS						Optional element. The section for the conditional execution adaptor parameters. Contains an execution flow for a group of services based on a series of switch, case, and execute elements that can be nested to present a decision tree whose leaf elements are the IDs of the service to execute.
	switch					Required element. The switch element. The `on` attribute specifies the alias name on which the switch is based.
	on					Attribute. Specifies which alias to switch on. The data type is string.
		case				Required repeating element. The case element. The value attribute specifies the value of the switch.
		value				Attribute. Specifies which match of the alias brings you to the inside of the case element. The data type is string.
			execute			Optional element. The ID of the service to execute if a case match occurs. The data type is string.
			switch			Optional element. The switch element. The on attribute specifies the alias name on which the switch is based.
			on			Attribute. Specifies which alias to switch on. The data type is string.
				case		Required repeating element. The case element. The value attribute specifies the value of the switch.
				value		Attribute. Specifies which match of the alias brings you to the inside of the case element. The data type is string.
					execute	Optional element. The ID of the service to execute if a case match occurs. The data type is string.
				default		Optional element. The branch to follow if no case match occurs.
					execute	Required repeating element. The ID of the service to execute if no case match occurs. The data type is string.
		default				Optional element. The branch to follow if no case match occurs.
			execute			Required repeating element. The ID of the service to execute if no case match occurs. The data type is string.

C.2.8 oracle.ds.engine.ea.DSFailOverExecutionAdaptor

A Failover Execution Adaptor schema contains the data shown in Table C-12. Required data is designated by bold element names. Element names are indented to show the relationship and hierarchy of elements. See Example 6-31 to view the contents of a sample failover execution protocol adaptor parameters section contained within the service body description.

Table C-12 Descriptive Matrix of the Failover Execution Adaptor Parameters

Element Name		Description
FAILOVER_EA_PARAMS		Optional element. The section for the failover execution adaptor parameters. Contains an execution priority value list of services to execute in the event that a service fails to execute.
	execute	Required repeating element. The execute element. The priority attribute defines the priority among the services.
	priority	Attribute. The value determines the execution priority. Data type is a non-negative integer.

C Descriptive Matrix