EGL services and Web services

A service is a set of operations that can be invoked by a client, which is an application component that resides on the same or another platform. A service that you develop in EGL can be deployed in either or both of these ways:
At development time, the service is a part that includes implementation code. Here is a simple example:
  Service echoString
    function returnString 
      (inputString string in) 
      returns (string)

      return (inputString);
    end
  end
The Service part is similar to a library part:
Libraries and services differ in the following ways:

Instead of using a Service part directly in your code, you create a variable that is based on that part. The Service part includes the logic for the runtime service but does not include the details necessary for access. At run time, however, the variable is bound (refers) to a service that runs at a specific location. The binding includes details on the protocol that is used to access the service.

You specify the binding information in a variable declared in a service binding library, which is a type of EGL library. The variable is global to the run unit, as is true of any variable accessed directly from an EGL library. For most uses, the initial binding for that variable provides all the service-specific functionality needed by any client in the run unit.

The setting of the library property runtimeBind determines whether the initial binding of a variable to a service is based on a decision made at development time or at deployment time:
For advanced uses, EGL provides these capabilities:

To provide access to a non-EGL Web service, you must use an EGL interface. An interface also provides a secondary way to access a service that was developed in EGL. For an introduction to this subject, see EGL interfaces.

Runtime processes

Any EGL client accesses a service by way of a generated proxy that contains function descriptions equivalent to those in the service. The following configurations are possible:
  • An EGL client accesses an EGL service by direct connection, in which case the client and service are in the same run unit.
  • An EGL client accesses an EGL service by way of TCP/IP, in which case the EGL runtime is used on both the client and service side of the interaction
  • An EGL client accesses a Web service, in which case a Web Service Description Language (WSDL) definition is used on both sides of the transmission:
    1. The generated proxy invokes a Java JAX-RPC stub that was created when EGL generated the service binding library.
    2. The stub uses the information from the WSDL definition to send an XML-based, Simple Object Access Protocol (SOAP) message to the service. That message includes a valid mapping between an EGL-generated data type and the type of data submitted to or received from the service.
      Note: In most cases the default transformations are sufficient; but you can override a default by setting the @xsd property for a particular field, as described in @xsd.
    3. The stub receives the returned SOAP message, which is either business data from the Web service or an exception of type ServiceInvocationException. For details on the latter, see EGL system exceptions.
    4. The stub uses the information from the WSDL definition, in this case to convert data from the SOAP data types into the Java data types expected by the proxy.
    5. The stub returns data and control to the proxy.
    6. The proxy returns control to the client.
When an EGL-generated Web service is in use, the following events occur on the service side of transmission:
  • In response to its invocation, the Web services runtime code uses the service-side WSDL definition to create data that the service can use.
    Note: EGL generates a WSDL definition with the Web service and uses (in most cases) a default transformation of EGL-generated fields to WSDL elements. You can override a default by setting the @xsd property for a particular field, as described in @xsd. In this case, the purpose of setting the property is to establish a set of validation rules that limit the kind of data that will be provided to the service at run time.
  • The Web service runtime code submits the data to the Web service and acts as follows when the Web service returns data:
    1. Uses the service-side WSDL definition to create an XML-based SOAP message
    2. Returns that message to the client

Service bindings at run time

Consider the case of two services that provide identical operations but are on different servers. You can arrange for the client to select one or another service in response to a runtime condition such as a value retrieved from a database. You can achieve this flexibility in the following ways:
  • By use of a ServiceLib function that sets locations, as noted in ServiceLib; or
  • By use of multiple variables, as in the following steps:
    1. Create variables in a service binding library, that are based on the same Service part, and that are bound to different runtime locations.
    2. Declare a client variable that also is based on the Service part.
    3. Assign to the client variable one or another of the global variables, depending on conditions at run time. You can place the assignment statement in the OnException clause of a try block, as that clause will be invoked in response to a failed service invocation; specifically, in response to an exception of type ServiceInvocationException.
    4. Use the client variable to access the service.

    For details on ServiceInvocationException, see EGL system exceptions.

The use of multiple variables relies on the following rules:
  • The variable on the left side of the assignment statement receives a binding in these cases--
    • Only a variable is on the right side. That variable represents a service or interface that was declared in a service binding library or has received a binding in a previous statement.
    • Only a function is on the right side. That function returns a bound interface or service.
  • A function parameter receives a binding if the related argument has a binding.

Build descriptor options

When you generate an EGL service, the build descriptor option serviceRuntime is among those used; but the default value is sufficient.

When you generate a Web service, the following build descriptor options are among those used:
  • J2EELevel
  • serverType
  • serviceRuntime
  • WebServiceEncodingStyle
When you generate a service-binding library that references either a Web service or an interface that is bound to a Web service, the following build descriptor options are among those used:
  • J2EELevel
  • serverType
  • serviceRuntime

Deployment

Deploying an EGL service is equivalent to deploying a non-J2EE Java application. For details, see Deploying Java applications outside of J2EE.

Deploying a Web service is equivalent to deploying a Web application. For details, see Setting up the J2EE runtime environment for EGL-generated code.

Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.