EGL support for SOA

EGL provides two kinds of support for service-oriented architecture (SOA): service development and service access.

For a more basic introduction, see the following page at the EGL Development Tools web site:

Service development

With EGL, you start to develop a service by coding a Service part like the following one:
Service MyServicePart
   value STRING = "Hello, ";
   
   function myEcho(myString STRING IN) returns (STRING)
      return (value + myString + "!");
   end
end

The content of the Service part is the service implementation. In this case, the implementation accepts an input string such as “world” and returns to the requester the concatenation of “Hello,” the input string, and an exclamation point. You can make several functions, or service operations, accessible to service requesters.

When you create a Service part, you specify how to deploy it. You can deploy a Service part as one of the following kinds of services:
EGL service
An EGL service exchanges data in a binary format that is specific to EGL. An EGL service is accessible to other EGL code, and the access is relatively fast. However, the EGL service is not a web service and is not accessible to code that is written in another language.

If an EGL service is deployed with a Rich UI application, the service is identified as a dedicated service, which means that the Rich UI application has access to the service logic without referencing a service binding. This usage is convenient because you do not need to be aware of a separate address for service access.

EGL REST-RPC service
An EGL REST-RPC service is accessible to EGL-generated, web-based requesters. The data is always in JSON format, which cannot include HEX, BLOB, or CLOB data.

An EGL REST-RPC service access always uses a POST method, but that detail is hidden to the requester. For other details that are meaningful when you access an EGL REST-RPC service from logic written in another language, see “EGL REST-RPC message structure.”

In a Rich UI application, the EGL runtime code rounds any numeric data that is returned by the service and is greater than 15 significant digits. The rounding does not occur when JSON is returned to EGL-generated Java™ code.

SOAP service
A SOAP service is a traditional web service and is accessed by code that is written in any language.

Neither development nor access of SOAP services is available in version .7

Access to a generated service always conforms to the RPC style rather than to the RESTful style. The parameters and a return value identify the data to exchange. Access to the service does not involve path variables or query parameters.

Code development for service access

Any EGL logic part can act as a service requester; even a Service part. You can access the following kinds of services:
  • An EGL service.
  • An EGL REST-RPC service.
  • A SOAP service, whether or not it is generated.
  • A third-party REST service that largely fulfills the REST style. The following variations are supported:
    • Some REST services use a POST request for tasks other than creating a resource. When you access a third-party REST service with a POST request, you can avoid sending business data.
    • Some REST services require that a DELETE request include a representation (the business data) rather than relying on the URI to identify the resource to delete. EGL supports the access of REST services that require a representation for a DELETE request, but also supports access of REST services that do not have that requirement.
Service access typically involves the following steps:
  1. Specify a resource binding in the EGL deployment descriptor. The binding in this case is called a service binding because it has the details necessary to access the service. Configuration personnel can update the binding without updating and regenerating the requester.

    For services as for SQL, a resource binding has a type. For example, the type for REST or REST-RPC services is HttpRest.

  2. Create an Interface part that is based on the service. The Interface part includes function prototypes, which are definitions that identify the parameters and return-value types for each accessible function. You can write the Interface part manually or can use the workbench to create the Interface part from an EGL Service part.
  3. Declare a variable for which the Interface part is the type definition. The documentation typically refers to the variable as a service-access variable.
    Here is an example declaration:
    myService IMyService?{@Resource{bindingKey = "myBinding"}};

    The Resource annotation causes the variable named myService to reference the HTTPRest object named myBinding, which has values that you specified in the EGL deployment descriptor. If you do not specify the bindingKey field in the annotation, the EGL runtime code accesses those values from the binding entry that is named for the variable.

  4. Use the service-access variable in a service-invocation statement. For details about that statement, see “Service access in Rich UI” and “Service access outside of Rich UI.”

If you are accessing a service that was written in EGL, you do not need to create an Interface part, but can use the Service part as if it were an Interface part. However, your use of a separate Interface part lets you avoid distributing a service implementation to another developer. You might avoid distributing the implementation if it is changeable or confidential.

The process for binding a variable to access details can vary from what was shown earlier:
  • The variable declaration can explicitly identify the EGL deployment descriptor that contains the service binding. Here is an example:
    myService IMyService?{
       @Resource{bindingKey = "myBinding",
                 propertyFileName = "myDeploymentDescriptor"}};

    If you do not reference the propertyFileName annotation field, its value is the name of the EGL deployment descriptor that is used at deployment time.

    When you set the propertyFileName annotation field, do not include a file extension. The name of the file that is accessed at run time includes the following suffix: -bind.xml.

  • You can update binding details at run time, as shown in “Binding an access variable dynamically.”

Web service deployment

The runtime architecture for all EGL web service deployments has the same pattern: generated or runtime code acts as an intermediary between the requester and the service. The intermediary code converts data between the text-based format of a service message and the binary format required by the service.

Here is the overview for each kind of deployment:
  • When you generate an EGL REST-RPC service, the output is a set of Java classes. When you generate or deploy the deployment descriptor, the output includes an XML file that identifies the service location.

    The runtime platform is an application server that is compliant with Java EE. There, the EGL runtime code reads the XML file, invokes the service, and acts as an intermediary between the requester and service.

  • When you generate a SOAP service that is based on Java, the output is a set of Java classes. When you generate or deploy the deployment descriptor, the output includes a Java class that is known as a service wrapper. This service wrapper is distinct from the "Java wrappers” that you can generate with EGL.

    The runtime platform is an application server that is compliant with Java EE. The application server invokes the service wrapper, which in turn invokes the service and acts as the intermediary between the requester and service. The service wrapper and service are local to one another.

    Neither development nor access of SOAP services is available in version .7

Service access

Service access from an EGL-generated requester has a consistent pattern: a proxy acts as an intermediary between the generated requester and the service. The proxy converts data between the format used by the requester and the format required by the service.

The next table gives further details, by service type.

Characteristic of the requested service Characteristic of the deployed requester Characteristic of the proxy
dedicated EGL An HTML file that embeds JavaScript™ The proxy is in the EGL runtime code and invokes the service locally, without an HTTP request.
local EGL: not yet available. EGL-generated Java code No proxy is in use.
 
remote EGL: not yet available. EGL-generated Java code The proxy is in the EGL runtime code.
 
EGL REST-RPC: available only from JavaScript. EGL-generated Java code or an HTML file that embeds JavaScript The proxy is in the EGL runtime code.
REST available only from JavaScript EGL-generated Java code or an HTML file that embeds JavaScript The proxy is in the EGL runtime code.
 
SOAP: not yet available. EGL-generated Java code or an HTML file that embeds JavaScript and that is deployed on an application server that is fully compliant with Java EE, such as IBM® WebSphere® Application Server The proxy is a Java class that is generated from the requester-specific deployment descriptor.
An EGL-generated Java code or an HTML file that embeds JavaScript and that is deployed on any other platform The proxy is in the EGL runtime code.
 

Another aspect of service access is the location of service-binding detail. For all EGL-generated requesters, the detail is in an XML file that is generated from the requester-specific deployment descriptor and that is deployed with the requester.

Protocols

Access of web services always involves the HTTP protocol, but other protocols are used for accessing EGL services.