EGL support for SOA

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

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 ”and the input string. 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 various kinds of 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.

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.

Access to an EGL-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, including a Service part, can act as a service requester. The following kinds of services can be accessed:

An EGL service
An EGL REST-RPC service
A SOAP service, whether or not it is EGL generated
An IBM® i service program
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:

Specify a service binding, which are the details necessary to access the service. The service binding can be in the requester or in the EGL deployment descriptor. When possible, use the deployment descriptor because configuration personnel can update the service binding without updating and regenerating the requester.
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 or can use the workbench to create it automatically from an EGL Service part or a WSDL file.
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.
Declare a variable for which the Interface part is the type definition. For example, if the Interface part is named IMyService, the variable is named myService, and a deployment descriptor entry is also named IMyService, the variable declaration is as follows:
```
myService IMyService{};
```

For details about the types of data sent to or returned from services, see “Restrictions in the prototypes used for service access.”

Although you can use an EGL Service part as an Interface part, in most cases, use a separate Interface part. For example, you might want to avoid distributing a service implementation to another developer because the service is changeable or confidential. However, you must use a Service part as an Interface part when you are accessing a dedicated service from a Rich UI application, as described in “Service access in Rich UI.”

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 EGL-generated output that is described in “Generating Java wrappers.” 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.
When you generate a COBOL-based SOAP service for IBM i, the output is a COBOL program. When you generate or deploy the deployment descriptor, the output includes an EGL-generated service wrapper, which is a Java class.
The situation is like the case of a Java-based SOAP service, but the service wrapper is remote from the service. The runtime platforms are twofold:
- An application server that is compliant with Java EE invokes the local service wrapper, which acts as an intermediary between the requester and the EGL COBOL runtime code on IBM i.
- An IBM i installation runs the EGL COBOL runtime code. The runtime code includes a catcher program, which is logic that handles the data conversion between Java and COBOL.
The service wrapper uses the Java400 or Java400J2C protocol to communicate with the remote catcher program. The catcher program invokes the service and acts as an intermediary between the service wrapper and the service.
When you generate a SOAP service that is based on COBOL for CICS®, the output is a COBOL program. When you generate or deploy the deployment descriptor, a second EGL-generated COBOL program known as a service wrapper is provided for use by CICS. Another output generated from the deployment descriptor is a WSBIND file.
The runtime platform is CICS, which acts as follows:
- Uses the WSBIND file to translate the SOAP-envelope content to a binary format.
- Invokes the service wrapper, which acts as the intermediary between the requester and service.
The service wrapper and service are local to one another.

Service access

Service access from an EGL-generated requester has a consistent pattern: a proxy acts as an intermediary between the EGL-generated requester and the service. The proxy converts data between the format used by the requester and the format required by the service. However, no proxy is in use when an EGL service is local to the requester.

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	EGL-generated Java code	No proxy is in use.
local EGL	EGL-generated COBOL program	No proxy is in use.
remote EGL	EGL-generated Java code	The proxy is in the EGL runtime code.
remote EGL	EGL-generated COBOL program	Access is not supported.
REST or EGL REST-RPC	EGL-generated Java code or an HTML file that embeds JavaScript	The proxy is in the EGL runtime code.
REST or EGL REST-RPC	EGL-generated COBOL program	Access is not supported.
SOAP	EGL-generated Java code or an HTML file that embeds JavaScript and that is deployed on an application server that is fully compliant withJava 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.
	EGL-generated COBOL program	The proxy is a COBOL program that is generated from the requester-specific deployment descriptor.

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

EGL-generated Java and COBOL code are both in use when an EGL-generated COBOL program is deployed on IBM i and accesses a SOAP service. To understand the implication, be aware of the following runtime events:

The EGL-generated code calls the local, EGL-generated proxy.
The proxy calls the EGL COBOL runtime code; specifically, the catcher program that handles the data conversion between COBOL and Java.
The catcher program uses the Java Native Interface (JNI) to invoke EGL Java runtime code, which runs on the Java Virtual Machine (JVM) on IBM i.
The EGL Java runtime code accesses the SOAP service locally or remotely.

The initial call to the proxy is slow because the EGL Java runtime code is loaded, including all the JAR files in the classpath. The loading occurs only on the first call or after IBM i unloads the JVM from memory.

Security on the web

A Java runtime property specifies whether the exceptions returned by EGL REST-RPC services include the greatest possible level of detail. See "Description of Java runtime properties"; specifically, the entry for egl.service.rest.exception.debug, which took effect in version 8.5 and higher of the EGL runtime code.

Support for WS-Addressing and WS-Security

When you deploy EGL-generated SOAP services or EGL-generated SOAP service requesters to IBM WebSphere Application Server, you can use the WS-Addressing and WS-Security capabilities of that application server. The service or service requester must rely on JAX-WS rather than JAX-RPC, as described in “EGL support for JAX-WS and JAX-RPC.”

For additional information, go to any of the following sites and search for “WS-Addressing” or “WS-Security”:

Protocols

Access of web services always involves the HTTP protocol, but other protocols are used for accessing COBOL web services and in other cases. For details, see “Sharable protocols.”