1.3 Service Bus Components
Service Bus routes message between external services (such as enterprise services and databases) and service clients (such as presentation applications or other business services). The service and flow components you create in a Service Bus project rely on local and system resources in Service Bus to define additional information like user names and passwords, keystore credentials, server connections, and transformations.
Service Bus resources are reusable definitions of entities that typically include metadata for those entities. Multiple services can use resources and provide standardized definitions or descriptions for use across an enterprise or department.
1.3.1 Service Components
Proxy services and business services define the endpoints in a Service Bus system. They include the binding and transport layers, and are the points at which Service Bus communicates with external services, including producers and consumers.
1.3.1.1 Proxy Services
Proxy services are Service Bus definitions of generic intermediary web services that are hosted locally on Service Bus. A proxy service communicates with external services through interfaces, which may or may not be identical to that of a service provider or service consumer business service. Through pipelines, you can route messages from a proxy service to multiple business services using their configured independent interfaces.
A proxy service's configuration includes its interface (service type), the type and configuration of the transport it uses to connect with client services, security requirements, and service level agreement (SLA) alert rules. When a proxy service interfaces with multiple business services, its associated pipeline is configured to route messages to the appropriate business service and map the message data into the format required by the business service's interface.
For more information, see .
1.3.1.2 Business Services
Business services are Service Bus definitions of the enterprise services that exchange messages during business processes. A business service's configuration includes its interface (service type), the type and configuration of transport it uses to connect with service producers, security requirements, message handling, performance tuning, and SLA alert rules. A business service also specifies the endpoint URI, and can specify multiple endpoints for load balancing and high availability. A business service definition is similar to that of a proxy service, but with additional options for message handling, endpoint throttling, and result caching, which help improve performance.
You can create a service account to provide authentication when connecting to a business service. It acts as an alias resource for the required user name and password pair. You can also use Oracle WebLogic Server to directly manage security credentials for a business service requiring credential-level validation.
For more information, see .
1.3.2 Message Flows
A message flow defines how messages are routed, validated, and transformed between services. The message flow is typically defined in a pipeline, but can also be defined in a split-join for parallel processing.
1.3.2.1 Pipelines
Pipelines define message routing and transformation logic, as well as message handling options. This logic includes activities such as transformation, publishing, logging, reporting, alerts, and exception management. Each of these activities are configured as individual actions within the message flow. Both JDeveloper and the Oracle Service Bus Console provide graphical modeling tools to help you model your pipelines.
The following primary elements are used to construct a pipeline:
A start node.
A pipeline pair, one for the request and one for the response. Each pipeline in a pair consists of a sequence of stages that specify actions to perform during request or response processing.
A branch node, to branch based on the values in designated parts of the message or message context, or to branch based on the operation invoked.
A route node, to define the message destination. The default route node is an echo node that reflects the request as the response.
An error handler, which can be attached to any node or stage to handle potential errors at that location.
At a minimum, a start node and route node are required. While an error handler is not required, it is recommended. If an instance fails and no error handler is defined, the error is not recoverable. Pipeline elements can be combined in arbitrary ways to form a tree structure with the start node always (and only) occurring as the root of the tree and the route nodes. The last nodes in a branch (leaf nodes) can be route nodes or echo nodes.
Since a pipeline can route messages to multiple business services, a pipeline can be configured with an interface that is independent of the business services it communicates with. Using generic templates, the pipeline can be a configured to dynamically route messages to appropriate business services based on content-based routing logic. A pipeline can also map message data into appropriate protocol formats required by the end-point business service, allowing for dynamic runtime protocol switching.
For more information, see Working with Oracle Service Bus Pipelines
1.3.2.1.1 How Data Flows Through a Pipeline
In a pipeline, the request message starts at the start node and follows a path to a leaf node, executing actions in the request pipelines. If the leaf is a route node, a response is generated. If the leaf is an echo node, the request is also considered to be the response. The response follows the inverse path in the tree, skipping actions in the branch nodes but executing actions in response pipelines. A response is then sent from the top of the tree if the interface or operation was request/response; otherwise the response is discarded.
A set of transformations that affects context variables can be defined before the message is sent to the selected endpoint or after the response is received. A web services callout can be an alternative to an XQuery or XSLT transformation to set the context variables.
1.3.2.1.2 Message Context
The context of a pipeline is a set of XML variables that are shared across the request flow and response flow. New variables can be dynamically added or deleted to the context, and these variables can be shared across multiple pipelines or used locally within one pipeline. Predefined context variables contain information about the message, transport headers, security principles, metadata for the current pipeline, and metadata for the primary routing and publishing services invoked by the pipeline.
The context can be read and modified by XQuery or XSLT expressions, and updated by transformation and in-place update actions. The core of the context contains the variables $header, $body, and $attachments. These wrapper variables contain the Simple Object Access Protocol (SOAP) header elements, SOAP body element, and Multipurpose Internet Mail Extensions (MIME) attachments, respectively. The context gives the impression that all messages are SOAP messages, and non-SOAP messages are mapped to this paradigm.
1.3.2.2 Split-Joins
The split-join message flow improves service performance by splitting a message payload and processing multiple operations in a message simultaneously and then combining, or joining, all results. A standard pipeline processes operations one after another.
The following primary elements are used to construct a message flow in a split-join:
A start node, which contains the request and response variables introspected from the WSDL operation.
A receive node, to receive incoming request messages.
A reply node, to send response messages.
A scope, which is a container that creates a context that influences the behavior of its enclosed elements.
A parallel node, which is a placeholder for a fixed number of processing branches, each with its own scope.
The available elements can be combined in arbitrary ways to form a tree structure with the start node always (and only) occurring as the root of the tree. The last node is always the reply.
For more information, see .
1.3.3 Transports, Adapters, and Bindings
Service Bus provides connectivity to external systems through a variety of transports, each of which is specific to a type of external system. Service Bus supports optimized database queries, and interoperability with web service integration technologies such as .NET, IBM MQ Series, IBM WebSphere, Apache Axis, and iWay adapters. The JCA transport expands the list of supported technologies by letting you connect to external systems using Oracle JCA technology and applications adapters. Additionally, Service Bus supports the REST binding, allowing you to connect to RESTful services using the HTTP transport.
You configure a transport's processing and connectivity information directly within a proxy or business service; you configure Oracle adapters using a configuration wizard specific to each adapter.
For more information, see Working with JCA Adapters, Transports, and Bindings
1.3.3.1 Supported Transport Protocols
Service Bus supports the following transport protocols:
DSP (Oracle Data Service Integrator)
EJB/RMI
Email (POP/SMTP/IMAP)
File
(S)FTP
HTTP(S)
JCA
JEJB
JMS (including MQ using JMS, and JMS/XA)
Local (Oracle proprietary for inter-ESB communication)
MQ (WebSphere MQ)
SB (RMI support)
SOA-DIRECT (Oracle SOA Suite) and BPEL
Tuxedo (Oracle Tuxedo)
WS (Web Services Reliable Messaging
Service Bus also provides the Custom Transport SDK so you can create new transports to connect with systems not covered above.
1.3.3.2 Service Types
Service Bus supports a variety of service types ranging from conventional web services (using XML or SOAP bindings in WSDL files) to non-XML (generic) services. You select and configure the service type when you create a business or proxy service. The available service types for a proxy or business service depend on the transport being used. Service Bus supports request and response as well as one-way paradigms, for both the HTTP and the JMS asynchronous transport protocols. If the underlying transport supports ordered delivery of messages, Service Bus also extends the same support.
Not all service types can be used with all transport protocols. The following table shows the service types and the transport protocols they support.
Service Type
Transport Protocols
WSDL Based Service BPEL-10g, DSP, HTTP(S), JCA, JMS, Local, SB, SOA-DIRECT, WS JMS request and JMS response are not supported if WS-Security is enabled. Any SOAP Service (non-WSDL) HTTP(S), DSP, JMS, Local, SB JMS request and JMS response are not supported if WS-Security is enabled. Any XML Service (non-WSDL) DSP, email, File, FTP, HTTP(S), JMS, Local, MQ, SB, SFTP, Tuxedo HTTP GET is only supported for XML with no WSDL. Messaging Service email, File, FTP, HTTP(S), JMS, Local, MQ, SFTP, Tuxedo Business services using the email, File, FTP, or SFTP transport support one-way messaging services only; the response message type should be none.
Native REST Service HTTP(S), Local
The BPEL-10g, DSP, EJB, and SOA-DIRECT transports are only supported with business services.
1.3.4 Transformation Resources
In addition to creating inline XQuery expressions directly in message flow actions, you can reference transformation maps that define more complex mappings between source and destination services. When disparate message data types exist between source and destination services, data mapping ensures service compatibility. Service Bus supports data mapping using XQuery and eXtensible Stylesheet Language Transformation (XSLT) standards, along with XPath expressions. You can also use cross reference tables and domain value maps to map field values between services.
Messages can be transformed in the following ways:
Using XQuery or XSLT to reformat the message structure.
Manipulating message content by adding, removing, or replacing certain data elements.
Using cross reference or domain value map tables to map entities across systems.
1.3.4.1 XQuery Mappings
The XQuery Mapper in JDeveloper is a graphical tool that lets you define mappings that transform data between XML, non-XML, and Java data types so you can rapidly integrate heterogeneous applications. For example, XML data that is valid against one schema can be converted to XML that is valid against a different schema. The data can be based on XML schemas, Web Service Definition Language (WSDL) files, and Message Format Language (MFL) files. You can create an XQuery mapping in JDeveloper, and then upload the .xqy file generated by the mapper to an XQuery resource in the Service Bus Console. XQuery mappings are stored in XQuery resources in Service Bus, which can be referenced from the expressions you create using the expression editors in a message flow action.
The output of the XQuery Mapper is a query in the XQuery language, which is defined by the World Wide Web Consortium (W3C). For more information about W3C and the XQuery language, see .
For more information, see:
1.3.4.2 XSLT Mappings
eXtensible Stylesheet Language Transformation (XSLT) maps describe XML-to-XML mappings. The XSLT mapper in JDeveloper is a graphical tool that lets you define mappings between schema root elements, Web Services Description Language (WSDL) message parts, or WSDL messages. Schema root elements can come from XSD schema files or WSDL files. Only those WSDL messages that contain a single message part can be mapped directly.
The XSLT Mapper in JDeveloper lets you define transformations that apply to the whole message body to convert messages from one XML schema to another, enabling data interchange among applications that use different schemas. You can create an XSLT mapping in JDeveloper, and then upload the .xsl file generated by the mapper to an XSLT resource in the Service Bus Console. XSLT mappings are stored in XSLT resources in Service Bus, which can be referenced from the expressions you create using the expression editors in a message flow action.
For more information, see:
1.3.4.3 Cross References
Cross reference tables map identifiers that represent equivalent objects across multiple applications, associating like objects created in different external applications. They are used to manage the runtime correlation between the various applications that share data through Service Bus. For example, you can use cross references to map customer identifiers for records that were created in multiple customer management systems. Cross reference values can be updated during runtime, allowing you to dynamically integrate values between systems. Any cross reference data updated at runtime is persisted in the database. Cross references can be used across Oracle SOA Suite components. In Service Bus, you can create cross reference tables in both JDeveloper and the Oracle Service Bus Console.
Service Bus provides a set of XPath functions for looking up and modifying cross reference values. These functions are available to use in the expressions you create using the expression editors in a message flow action. For more information, see .
1.3.4.4 Domain Value Maps
A domain value map associates terms used by different domains to describe the same entity, providing the capability to map the terms across vocabularies or systems. For example, each domain might use different terminology for country codes, city codes, currency codes, and so on. You can enter these values in a map and look up those values at runtime to transform the data when passing it from one domain to another. Domain value maps are similar to cross references, but they are defined statically rather than dynamically. You create and populate domain value maps in the design time, and deploy them to the runtime. Domain value map data are not changed by runtime activities as it is for cross references, but rather the domain value maps are used for lookups only.
Domain value maps can be used across Oracle SOA Suite components. In Service Bus, you can create domain value maps in both JDeveloper and the Oracle Service Bus Console. Service Bus provides a set of XPath functions for looking up domain value map values. These functions are available to use in the expressions you create using the expression editors in a message flow action. For more information, see .
1.3.5 Transport and Adapter Related Resources
Some transports rely on specific types of files, such as JavaScript and JAR files or MQ connections. The JCA transport requires the JCA file and any files it references, such as a WSDL file. This section describes the resources that are specific to certain transports.
1.3.5.1 JCA Bindings
JCA binding resources in Service Bus let you create business and proxy services that interact with external services through Oracle SOA Suite JCA adapters. A JCA binding is made up of a service WSDL document and a corresponding JCA file created in Oracle JDeveloper. In JDeveloper, you can add a JCA adapter directly to a Service Bus project using the Service Bus Overview Editor by dragging and dropping the adapter type from the Components window to the editor's canvas. The proxy or business service is automatically generated from the JCA adapter configuration, and is based on the JCA transport. In the Oracle Service Bus Console, you need to upload the JCA file into a JCA binding resource in order to create a business or proxy service based on that JCA adapter. You can also import the JCA file and its associated WSDL file using the import feature.
For more information, see .
1.3.5.2 JAR Files (Archives)
A JAR (Java Archive) is a zipped file that contains a set of Java classes. It is used to store compiled Java classes and associated metadata that can constitute a program. A JAR acts like a callable program library for Java code elements, so a single compilation link provides access to multiple elements rather than requiring bindings for each element individually.
In JDeveloper, you can add JAR files to a project or component directly from the file system, but in the Oracle Service Bus Console, you need to upload each JAR file to add to a project into an archive resource. In Service Bus, JAR files are used the following components:
Java callout actions (in pipelines) that provide a Java exit mechanism
EJB-based business services
JEJB-based business and proxy services
Tuxedo-based proxy and business services
For more information, see .
1.3.5.3 JavaScript Files
JavaScript files are used by the JCA Socket Adapter as a mechanism for handling the handshake. XSLT and custom Java code are also supported handshake mechanisms. In JDeveloper, you can create a JavaScript file and then select the file when you configure a JCA socket adapter. You can also create the JavaScript when you configure the adapter. In the Oracle Service Bus Console, you can either upload an existing JavaScript file to a JavaScript resource, or you can create the text for the JavaScript in a text editor in the console. Alternatively, you can use the console's import feature to import the Socket adapter's JCA file and its dependencies, such as WSDL and JavaScript files.
Service Bus supports JavaScript handshake for both inbound and outbound socket adapters, and for one-way and request/response messaging. Request/response handshakes require a separate JavaScript file for the request and the response.
For more information, see .
1.3.5.4 MQ Connections
MQ connection resources provide the connection parameters required to connect to an MQ queue manager. They are used in proxy and business services configured to use the MQ transport, and can be shared and reused across multiple services. MQ proxy and business services must connect to an MQ queue manager before they can access an MQ queue. Each MQ connection resource uses a connection pool, and every business or proxy service that connects to a queue manager using the same MQ connection resource also uses the same connection pool. Thus, multiple business and proxy services can use the same queue manager and share a connection pool.
In order to create MQ connections in the Oracle Service Bus Console, you must install the WebSphere MQ client library to the Service Bus domain. This is described in .
1.3.6 Schema and Document Resources
Service Bus services rely on different document types to define information like message structures and web interfaces. These documents include XML schemas, MFL files, and XML files to describe data, and WSDL and WADL documents to describe interfaces.
Service Bus has a built-in type system that is available for use at design time. When creating an XQuery expression in a condition, in-place update action, or transformation, the variable can be declared to be of a given type in an editor to assist in easily creating the XQuery. The types can be the following:
XML schema types or elements
WSDL types or elements
MFL types
1.3.6.1 XML Schemas
XML schemas are documents that define valid content for primitive or structured data in XML documents. XML schemas specify the structure of documents, the data type of each element and attribute contained in the document, and the rules that XML business data must follow. XML schemas can import or include other XML schemas. Schemas are used to add XML information to messages exchanged in Service Bus, and may be required for XQuery expressions, WSDL files, and so on.
For more information, see .
1.3.6.2 XML Documents
XML document resources store XML files that can then be referenced when configuring proxy or business services. For example, you might use XML documents for TopLink mapping files needed in JCA proxy or business services that communicate with JCA-compliant systems.
XML documents are a standard feature in JDeveloper. In the Oracle Service Bus Console, the easiest way to create XML documents is to use the import feature. For example, if you import JCA resources (JCA file, along with its associated WSDL and mapping files), Service Bus automatically generates XML document resources out of mapping files and maintains the dependencies among resource files. You can also create an XML document resource, and upload the contents of an XML file to the resource.
For more information, see .
1.3.6.3 WSDL Documents
A Web Service Definition Language (WSDL) interface defines a service interface for a SOAP or XML service. For web services, a WSDL document describes what the web service's interface is, where it resides, and how to invoke it. Service Bus defines proxy and business services in terms of two WSDL entities:
The abstract WSDL interface, which defines the operations in that interface and the types of message parts in the operation signature.
The binding WSDL interface, which defines the binding of the message parts to the message (packaging), and the binding of the message to the transport.
A WSDL file can also describe the concrete interface of the service (for example, the transport URL).
You can base the definition of a proxy or business service on an existing WSDL file, which automatically configures portions of the service. WSDL files used as the basis for defining services are stored as Service Bus resources. In JDeveloper, you can create WSDL files using the built-in WSDL editor. You can then import those WSDL files, and any schemas used by the file, into the Oracle Service Bus Console. The console can also be used to resolve the references in the WSDL files, ensuring all schemas and WSDL files are linked correctly. Service Bus uses its own representation of the interface for messaging services.
For more information, see .
1.3.6.4 WADL Documents
A Web Application Definition Language (WADL) document is similar to a WSDL document, described above, but it is specifically used to described the interface for REST proxy or business services. When you create a proxy or business service based on the REST binding in JDeveloper, the required WADL document is automatically generated from the WSDL document you specify for the binding. A WADL file can have dependencies on a WSDL file and on one or more XML schemas.
If you are using the Oracle Service Bus Console, you can create WADL documents by importing them or by creating a WADL resource. For more information, see .
1.3.6.5 MFL Resources
Service Bus uses Message Format Language (MFL) to describe the structure of typed non-XML data. MFL is an Oracle proprietary language used to define the rules that transform formatted binary data into XML data. MFL documents are used at runtime to transform an instance of a non-XML data record to an instance of an XML document (or the other way around).
You create MFL documents using the Format Builder tool in JDeveloper. The Format Builder allows you to describe the layout and hierarchy of the non-XML data so it can be transformed to or from XML. Using the Format Builder, you define each field in the message, including the type and size of data, the name of the field, any delimiters, and so on. You can also indicate whether the field is repeating, and whether it is optional or required.
For more information, see .
1.3.7 Security Resources
Security information can be passed through proxy and business services using service accounts, which define how the user name and password are obtained, or using service key providers, which define encryption credentials.
1.3.7.1 Service Key Providers
Service Key Provider resources contain Public Key Infrastructure (PKI) credentials used by proxy services for decrypting inbound SOAP messages and for outbound authentication and digital signatures. PKI credentials are private keys paired with certificates that can be used for digital signatures and encryption (for Web Services Security) and for outbound SSL authentication. The certificate contains the public key that corresponds to the private key.
Service Bus uses service key providers to supply the following types of credential-level validation to proxy services.
SSL client authentication
Digital signature
Encryption
Web Services Security X509 token
For more information, see .
1.3.7.2 Service Accounts
Service account resources provide user names and passwords that Service Bus uses for authentication when connecting to a service or server. Service accounts are used by proxy and business services for outbound authentication or for authentication to a local or remote resource, such as an FTP server or a JMS server. You can configure a service account to use a specific user name and password pair, to use the user names and passwords received from incoming requests, or to map user names and passwords provided by clients to user names and passwords you specify. One service account can be used for multiple business and proxy services.
For more information, see .
1.3.7.3 WS-Policy Resources
In previous versions, WS-Policy resources were used to store custom web service policies so they could be referenced by multiple WSDL documents. Beginning in 12c, Oracle Web Services Manager (OWSM) policies replace WLS9 policies, so there is no longer an option to create new services with WSDL-based WLS9 policies. While WS-Policy resources are still visible in imported projects, the associated web services should be updated to use OWSM policies. However, you can still import and activate a project from a previous version that uses WS-Policy resources.
1.3.8 Alert Destinations
An alert destination resource defines a list of recipients that can receive alert notifications from Service Bus. For example, when a service level agreement (SLA) or pipeline alert is generated, you can specify that notifications be sent to specific email addresses or JMS queues, ensuring that only the relevant people receive the notifications. An alert destination could include one or more of the following types of destinations: the Service Bus reporting data stream, SNMP trap, alert log, email, JMS queue, or JMS topic. In the case of email and JMS destinations, a destination resource could include a list of email addresses or JMS URIs, respectively.
For more information, see .
1.3.9 Throttling Group Resources
Throttling helps improve performance and stability by preventing message overload on high-traffic business services. To control the flow of messages to a business service and prevent backlogs, you can enable and configure message throttling for a business service or group of business services in your Service Bus applications. When messages are throttled, the business service can only concurrently process the number of messages you specify. When that capacity is reached, messages are stored in an in-memory queue until the business service is ready to process more messages.
For more information, see "Configuring Business Services for Message Throttling" in Administering Oracle Service Bus.
1.3.10 System Resources
System resources are globally available resources that can be shared across all projects in your Service Bus instance. They define server connections and authentication information, and include the following:
In the Oracle Service Bus Console, system resources are stored in a separate project named System. In JDeveloper, system resources are stored in the Application Resources panel under Service Bus System Resources.
1.3.10.1 JNDI Providers
JNDI provider resources define the connection and authentication information needed to access JNDI-named objects. They describe the URL (or list of URLs in the case of clustered deployments) of the JNDI providers used by Service Bus. For example, in a business service used to invoke an EJB, you include the name of a JNDI provider resource in the endpoint URI. When the business service is invoked, Service Bus uses the details in the referenced JNDI provider resource to make the initial connection to the JNDI provider.
If the JNDI provider is secured, then the JNDI provider resource also defines a user name and password to gain access. JNDI providers offer a great deal of flexibility. If a JNDI connection changes, you only need to modify the JNDI provider resource, and anything that references the JNDI provider automatically uses the updated configuration.
For more information, see .
1.3.10.2 SMTP Servers
SMTP server resources define the address of SMTP servers corresponding to email destinations, port numbers, and, if required, authentication credentials. They describe the URL for the SMTP servers used by Service Bus. If the SMTP server is secured, the SMTP server resource description also includes a user name and password to gain access. SMTP server resources are referenced when configuring alert destination resources and email transport-based business services.
For more information, see .
1.3.10.3 Proxy Servers
Proxy server resources define the connection and authentication information needed to access JNDI-named objects. They describe the URL for the proxy servers used by Service Bus. If the proxy server is secured, the proxy server resource description also includes a user name and password to gain access. You can use a proxy server to proxy requests from a client application, and you typically use a proxy server when Service Bus is behind a firewall. When you configure business services to route messages through a proxy server, associate the proxy server resource with that business service. This instructs Service Bus to connect to the business service through the configured proxy server.
You can configure multiple proxy servers for each proxy server resource. In this case, Service Bus can perform load balancing and offer fault tolerance among the configured proxy servers.
For more information, see .
1.3.10.4 UDDI Registries
Universal Description, Discovery and Integration (UDDI) registries are used to share web services. UDDI provides a framework in which to classify your business, its services, and the technical details about the services you want to expose. A UDDI registry resource stores information about a UDDI registry accessed by Service Bus for service discovery, publishing, and synchronization. After the UDDI registry resource is configured, you can publish Service Bus proxy services to the associated registry, or import business services from the registry to be used by a proxy service. UDDI registry resources define the inquiry, publish, security, and subscription URLs, along with a user name and password to gain access to the registry.
For more information, see .