To provide additional details about how to access the REST
service, you declare a variable in the requester. That variable is
based on the Interface part.
For example, here is
a declaration that is based on an Interface part named
WeatherForecast:
myService WeatherForcast {@RESTBinding {baseURI="http://www.ibm.com/gateway"}};
In that declaration, you can specify either of two properties,
each of which gives you a way to specify the following details:
- The initial value of the base URI, which is a set
of high-level qualifiers for the service location.
- The session cookie ID, which is a string that identifies
the session cookie that is provided to the EGL Rich UI proxy from
a service. The service logic in this case is stateful, which means
that the user and logic can participate in a multistep conversation.
This setting is meaningful if an EGL external type makes an IBM® i program or service program
available as an EGL REST-RPC service and if the requester is a Rich
UI application. For background information, see "Accessing IBM i programs as web services."
When
you use stateful REST services, the connection and all the associated IBM i resources are retained until
the session on the service side is invalidated. The service-side session
is invalidated when the requesting code invokes the serviceLib.endStatefulServiceSession() system
function or when the application server invalidates the session, typically
because of a timeout.
The two properties are @RESTBinding and @BindService.
You can use the @RESTBinding property to
specify the base URI and session-cookie ID directly in your code.
This option is simple but inflexible. You can use the @BindService property
to specify those details in a deployment descriptor, as allows for
changes at configuration time.
The two properties are mutually exclusive:
- @RESTBinding
- Use this property to specify, in your code, the base URI in the
code, the session cookie ID, or both. @RESTBinding includes
the following fields:
- baseURI
- A string that identifies the first qualifiers in the URI that
is being used to access the service. The default value of baseURI is
an empty string.
- sessionCookieID
- The name of a session cookie. The default value is JSESSIONID,
which is always the session ID when your application runs on Apache
Tomcat.
The setting of the
sessionCookieID field
is meaningful only in the following cases:
- The service is an EGL external type that makes an IBM i called program or service program available
as an EGL REST-RPC service; and
- The service logic is stateful, which means that the
requester and service can participate in a multistep conversation
The value of this field overrides the setting of the defaultSessionCookieID build
descriptor option.
- @BindService
- Use this property to use a deployment-descriptor entry to identify
the base URI, the cookie-session-ID, or both. The property has one
field:
- bindingKey
- Identifies the deployment-descriptor entry that includes the two
details.
You can specify the
@BindService property
without specifying the
bindingKey field.
In that case, the property identifies the deployment-descriptor entry
that has the same name as the Interface part. Here is an example of
that usage, which refers to the deployment-descriptor entry named
WeatherForecast:
MyService WeatherForecast {@BindService{}}
For
details about setting up the EGL deployment descriptor, see “Adding
a REST binding to the deployment descriptor.”