Integration Manager User's Guide
CHAPTER 13
A service is Integration Manager's basic unit of execution: It is a Integration Manager object (an xObject) that wrappers the various components you build, so as to create a logical unit of processing within the application server environment—one that's initiated with a request and results in a response. A service typically responds to a request by executing one or more components in a sequential and/or conditional manner (and can even execute other services). It can be, but doesn't have to be, exposed on a URL and triggered by a servlet.
Because the service xObject is the entry point for all web apps built with Integration Manager, it's important that you understand the design philosophy behind services and how Integration Manager's runtime architecture handles services. This chapter will tell you what you need to know in order to build and use services effectively.
The term Web Service, as used in this discussion, is generic. It refers to any Integration Manager-created service running on the app server, whether triggered by a servlet request in an HTTP session, arrival of e-mail, direct invocation by a custom Java class, or some other mechanism. It may (but doesn't always have to) refer to a web-facing service that is described by WSDL.
A SOAP service, in Integration Manager, is not a service type per se, but a way of specifying how a service needs to be invoked (and how its data needs to be marshalled or unmarshalled) on the server. In Integration Manager, you specify SOAP-HTTP as a trigger type. A specialized type of servlet is used to trigger the service.
It's also important to note that a given service can be associated with different trigger types. For example, it is possible (though perhaps not likely) that you would deploy a service with several triggers: a servlet-based trigger that handles data passed via HTTP GET; another servlet (on another URL) that handles data arriving via a form field using HTTP POST; and another that expects data passed in a String object, programmatically, via a custom application running locally on the server.
Integration Manager supports two types of services: Web Services, and JMS Services. (JMS stands for Java Messaging Service, a Sun-defined interface for message oriented middleware.) Your project, deployed (typically) as an EAR file, might contain one or more of either or both kinds of services. The two service types are referenced by two different icons under the "Service" heading of Integration Manager's navigation frame (see below).
The JMS Service type will not be visible to you in Integration Manager if you have not installed the Novell Integration Manager JMS Connect. The Web Service category, however, is always visible.
The defining characteristic of a JMS Service is how it is triggered. If a service that uses enterprise messaging will be triggered via the web, it must be created as a Web Service. If it will be triggered by arrival of a message, it must be created as a JMS Service.
A service is actually a specialized type of Integration Manager component. As mentioned earlier, a service has an action model and can perform most of the tasks that components perform, including XML mapping, looping, logging, fault-trapping, conditional processing based on Decision and Switch actions, etc. For reasons of good design, you should limit these tasks to an exception basis only, delegating business logic to underlying components. The main actions you should use in a service are Component, Log, Decision, Function, Try/On Fault, and Throw Fault. (See Building a Service with Components for examples of how a service uses these actions.) Anything connectivity-related, data-related, or implementing business logic, should happen at the component level.
NOTE: You can execute any number of components of any type (JDBC, XML Map, LDAP, etc.) in a service; and you can fire off those components synchronously (in serial, one-by-one fashion) or asynchronously (all at once). Also bear in mind that a service can invoke another service.
Using the service as the basic unit of processing in an application server should be a major goal in the design of your Integration Manager applications.
An Integration Manager Web Service can be, but doesn't have to be, a WSDL-described service deployed on a URL. In simplest terms, an Integration Manager Web Service is merely a component that calls other components. What makes it a "service"instead of a component is that the Web Service xObject can be triggered via a servlet or Java object on the server, whereas Component xObjects are not triggerable this way. (Components are called by services.) What makes a service a "Web Service" in the conventional sense of the term is exposure of the service as an endpoint as described in an associated WSDL file.
An Integration Manager Web Service can implement any of the interaction patterns alluded to by WSDL: notification, one-way, request-response, or solicit-response. It can be deployed on a public URL or it can be executed as a local app. It can be associated with WSDL, or not; and it can accept SOAP requests, or not.
The following picture shows the parts and function of a Web Service and is explained below.
In the drawing, the large rectangular grey box represents a Web Service. The shaded oval shapes with numbered text represent actions in the Action Model. The input and output XML files (squares) and the called components (small rectangles outside the service) are visible.
The purpose of this service is to receive an invoice (in an industry standard format) and to notify the sender that the invoice was received. Accomplishing the service requires some manipulation of the invoice, which is received as an XML document.
Here is how the service works.
The service is invoked by its Service Trigger (an object created at deployment time, designed to start a service in response to some external event). The servlet can be started by a business partner's application server issuing an HTTP Post to the servlet; or, alternatively (as shown by the longer grey arrow), the servlet could be invoked programmatically by a Java process on the host server.
The first job of the service, in this example, is to execute a Log action to write a file to record the activities of the service as they are executed.
The service then executes a Component action to call the Convert to My Format component.
The Convert to My Format component uses an industry standard invoice format as input and returns an XML file formatted to the company's internal format (My Format), as output.
The service executes another Component action to call the Send Email component. The My Format file is the input for the Send Email component.
The Send Email component executes several actions (extracts an email address from the invoice using the XML Interchange action, sends an email using the Send Mail action, and so on) and returns an XML file, eMail.
The following graphic shows the parts and functions of a JMS Service.
It is important to note that the JMS Service does not differ substantially from the Web Service discussed earlier; it differs mainly in that it is invoked by the arrival of a message on a queue (or topic, in Publish/Subscribe parlance). The JMS Service implements a MessageListener object whose onMessage() method is called automatically when a message arrives at a queue or topic with which the listener has registered. The onMessage() method executes the service.
The JMS Service must, by its nature, contain one (and only one) Receive Message action, created using the JMS Connect. The Receive Message action allows the service to gain access to the incoming message's data and properly acknowledge its receipt.
The remainder of the Action Model is the same for this service as for the preceding Web Service.
NOTE: This example is relevant only if you have purchased and installed the Novell Integration Manager JMS Connect.
You create a new service just like you create a new XML Map component. If you have not yet created any XML Map components, you must create any required XML templates before creating a service. For more information, see Creating an XML Template.
When you create a service, you specify input and output templates, just as you do for a component. If your service is designed to call components, rather than process data directly, the input template you choose for the service will often be the same template that the first component uses. The output template will often be the same one that is output for the final component in the sequence.
If you intend to create a SOAP service that uses custom SOAP headers, you should create XML Templates for the headers separately
From the Integration Manager window File menu, choose New, then xObject, then from the Process/Service tab, select Web Service.
Type in a Name and an optional Description.
You can use the optional description fields to describe the tasks the service performs.
Specify the input and output templates as follows. See About Specifying XML Templates for a Service for some tips.
Type in a name under Part if you wish the Message Part name to appear in the Component Editor as something other than "Input" or "Output."
Select a Template Category if it is different than the default category.
Select a Template Name from the list of XML templates in the selected Template Category.
To add additional input XML templates, click Add and repeat steps 2 through 4.
To remove an input XML template, highlight an entry and click Delete.
Click Next. The Temp/Fault Templates panel displays.
If desired, specify a template to be used as a scratchpad under the "Temp Message" pane of the dialog window. This can be useful if you need a place to hold values that will only be used temporarily during the execution of your component or are for reference only. Under the "Fault Message" pane, select an XML template to be used to pass back to clients when an error condition occurs.
As above, to add additional XML templates, click Add and choose a Part Name, a Template Category and Template Name for each. Repeat as many times as desired. To remove an input XML template, select an entry and click Delete.
Click Next. The In put/Output Headers panel displays:
Using the methods described above for adding Input, Output, Temp and Fault Documents, specify Input and Output Header Parts for your service if it will be used with a SOAP Service Trigger.
Click Finish. The component is created, and the Service Editor appears.
If your templates have namespace declarations, Integration Manager will generate a Declare Namespaces action for you automatically, at the top of your new Action Model.
Creation of JMS Services occurs via a wizard that has much in common with the Web Service wizard. For step-by-step instructions, see the Integration Manager JMS Connect User's Guide.
The import feature allows you to create a copy of an Integration Manager service created in another project. Once imported, you can customize the service for use within the current project.
Right-click on the Service item in the Integration Manager window, or choose Import xObject from the main File menu.
In the File Name field, type in the name of the service you wish to import, or use the Browse button to find it. If you import a file from a URL, you must explicitly type "http://," "https://," or "ftp://."
The Service Editor is (usually) where you specify the execution of components and services as well as perform error logging, decisions, and functions. You can also map, transform, and transfer input and output structure and data.
The Service Editor provides a logical working environment for visualizing and manipulating the inputs, output, and actions of your service. The Service Editor is composed of multiple mapping panes and a single Action Model pane. The mapping panes display the DOMs of your sample input and output documents. The Action Model displays actions that operate on the DOMs.( This environment is essentially the same as the XML Map Component editor.)
The Service Editor has all the same functions as the XML Map Component Editor. For more information on using the Service Editor, see the following topics:
A service is usually made up of one or more Component actions, each of which performs a specific task to map, transfer, and/or transform data for use by the next component or service called in the application.
You use the Component action to call and execute a component or service with runtime input DOMs and outputs DOMs that you specify.
Select a line in the Action Model where you want to place a call to a component or service. The new action is inserted below the line you select.
From the Action menu, select New Action then Component. The Action Component Information dialog box appears.
Select Predefined, by clicking on the radio button, if it is not already selected. (See Chapter 7 for a discussion of Predefined versus Dynamic Component Actions.)
Select a Component Type from the pulldown menu on the upper left.
In the Returned ID field, select either Output or Temp for the Message Part.
When you add Component actions to a service, they appear in the Action Model pane of the Service Editor. A service's Action Model represents the sequence in which components are called.
An example Action Model is shown below.
The Action Model functions has some logging functions and executes components as follows:
The first component action calls a component (ProductLookup). It specifies the DOM to be passed as the input document handle (Input) through which the component receives data from the service, and specifies the DOM to receive the component's output (ProductLookupOutput).
The second component action calls a component (InventoryLookup). It specifies the DOM to be passed as the input document handle (Input) through which the component receives data from the service, and specifies the DOM to receive the component's output (InventoryLookupOutput).
The third component action calls a component (MergeProductAndInventory). It passes the DOMs ProductLookupOutput and InventoryLookupOutput which the component receives data from the service as its Input and Input1 DOMs, and specifies a service DOM to receive the component's Output (Output).
Integration Manager provides a variety of Connect components that access different computing environments. The inputs and outputs of all component types are simply XML documents, This means that the communication between different component types is straightforward and simple.
There are two basic methods for passing data between components. The first method uses a service to pass and receive the inputs and output from individually called components. In this method, the components don't interact directly, but instead use the service as their point of contact. The second method uses the components to call one another directly. Which method you choose depends on how you design your services and the types of tasks they perform.
It depends how the service is deployed. If it is deployed as a SOAP service, your SOAP server may pass multiple input documents to your service (if multiple inputs are specified in your service's WSDL). In all other cases involving the four canonical Integration Manager service trigger types—Params (URL/Form), XML (MIME multipart), XML (HTML form field), and XML (HTTP POST)—only one XML document can be accepted as input.
For information on deployment, see your Integration Manager Enterprise Server User's Guide.
If you create a project with one service which calls two components, it is an acceptable design to have the first component call a third component before returning its output to the service which then calls the second component. Technically speaking, the third component is not "contained within a service" or called directly from it. The key idea to understand about a service is that only a service can be called by a "Service Trigger" object on the application server. Components don't have to be directly linked to a service, but if a component is not called somehow in the chain of events, it will never execute.
A Service Trigger object is the Java Servlet, EJB, or MessageListener (in the case of JMS) that you create with Integration Manager's deployment framework. This object is triggered by a URL either embedded in a Web page or called from another program on the Web. Once triggered, the Servlet or EJB starts an Integration Manager service.
Again, for information on deployment, service triggers, framework objects, etc., see your Integration Manager Enterprise Server User's Guide.
Projects are deployed as JAR files, and normally, if any services or components in your project need to call on other services and/or components, the "called" services/components will reside in the same JAR file. But on occasion, you may find it convenient (or necessary) to have a service call another service that exists in a different JAR file (that is, another deployed project). You can do this by means of the XML Interchange action.
The XML Interchange action allows your component or service to output an XML document via HTTP GET, PUT, or POST protocols. By supplying the URL for another Integration Manager service, you can have your XML Interchange action fire the servlet trigger for the service in question. See the diagram below.
In this diagram, Web Service 2 in Project A wishes to call Web Service 3 in Project B. Although Web Service 2 can call Web Service 1 directly, since it resides in the same project JAR, it cannot reach Web Service 3 directly. Instead, it must execute an XML Interchange action, which fires the service trigger for the remote service.
Log Actions write information about the activities of components within services. To create a single log file in which to record the activities of all components within a service, simply specify the same file name in the Log to: field for every Log Action used in the service and each component. Refer to The Log Action for more information about Log Actions.
NOTE: When specifying the same file name for multiple log actions, make sure you do not select the Clear the Log File checkbox. Doing so will erase the log file before each log action writes to it. You may, however, want to select this option for the first Log Action encountered in the service; this clears the log so you can troubleshoot or animate an action model multiple times without continuously appending messages to the end of the file.
Similar to using components, the XML template(s) you use as the Input(s) to your service may contain multiple sample documents. During testing, as you step through the actions in the service, you can load the appropriate sample documents to verify that the service can handle each instance.
For more information, see Loading a Sample Document.
Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...
