Chapter 8: Services, Packages and Request Handlers

This chapter describes service, package and request handler objects, the relationships between them and what you can do with them.

Introduction

Service objects, implementation package objects and request handler objects work together to enable service-based business functionality to be provided. A service object for a business service (as opposed to a system service) must have exactly one request handler and one implementation package associated with it. It can have one or more service listeners associated with it.

For all three kinds of objects, your responsibilities as administrator include:

• Adding, updating and deleting objects as required
• Monitoring the status of objects and investigating any problems

Creating Services Manually

When you deploy a service using the Interface Mapping Toolkit, all the objects required are created automatically, complete with their relationships. However, if you add services manually to an enterprise server, you need to create the objects for them and their relationships in a certain order, as follows:

1. Add the implementation package to the enterprise server
2. Add one or more service listeners
3. Add the service, and associate the listener or listeners, implementation package and request handler with it

Additions, Updates and Deletions

You can add services and implementation packages to an enterprise server, and update and delete them whether or not the enterprise server is running.

If the enterprise server is running (that is, if it has the status "Started") when you are adding services and packages, the changes are immediately reflected in the enterprise server. As long as the service is not currently responding to a client request, any updates are also accepted and take immediate effect.

You cannot delete a service, package or request handler if the resources are in use by a client request. You cannot delete a package if it is associated with a service, whether or not the service is running. If a service has operations, you can delete a service and all its operations and packages in one step, or you can delete individual operations and packages.

When you delete services, packages and request handlers, you are deleting objects in the Directory Server repository, not physical files. Every time a developer deploys a service using the Deploy tool or the imtkmake command, a new directory is created in the enterprise server's deploy directory to hold all the deployed files. If a developer redeploys a service that has already been deployed, the old deployment directory is no longer referenced, since the old service and package objects will have been deleted. You might want to delete old deployment directories from time to time.

If an enterprise server is running and you add, edit or delete resources, administration messages are sent to the enterprise server console indicating the success or otherwise of your changes.

It is possible for the Directory Server repository to become out-of-step with a live enterprise server if the Directory Server accepts updates that Enterprise Server rejects. If this happens you should stop the server and restart it to enable it to pick up the updates.

Services

A service provides access to specific business functionality.

Services that have been deployed using the Interface Mapping Toolkit always contain one or more operations. For example, if you work through the interface mapping tutorials in your Getting Started book, you create a service wmapserv with four operations, Add, Read, Next and Delete. The Enterprise Server documentation uses the term "service with operations" for services of this type.

A service that you create within Enterprise Server can contain one or more operations, depending on the name you give the service and which request handler is associated with it (if any). If you create a service with no request handler associated with it or if the name you use does not contain a valid separator, the service and the operation are one and the same. The Enterprise Server documentation uses the term "simple service" for services of this type. System services such as the Deploy service of the default enterprise server ESDEMO are simple services.

Service names can be of two forms, depending on whether or not the service contains any operations. The two forms are:

• Names consisting of one part, for example, Test or my_service. Simple services have this type of name.
• Names consisting of three parts, for example, http:/tempuri.org/wmapserv#Add. The parts are:
  • The service namespace. This is the part of the name before the first pound (#) character
  • The separator, in this case, the pound (#) character
  • The operation name, in this case Add

  Services with operations have this type of name.

  Service names for Web services use the first pound (#) character as a separator, while names for services that form part of a J2EE application use the last period ( ) character, for example, mybinpservice.operation.

  You can include more than one pound character or period in a service name; Enterprise Server will interpret the first pound character or last period character it finds as the separator.

The Services Table

You can see the information held in the repository for services by clicking Details against Services in the table of servers on the Home page. The services table is shown in Figure 8-1.

Figure 8-1: Services Table

The information is as follows:

• Service namespace - a unique label within the enterprise server that identifies the service and if it contains operations, groups the operations together
• Operation - a list of the individual operations within a service; if the service is a simple service, there is just one item in this list, and it bears the same name as the service itself
• Service class -a further qualifier for a service; client requests can look for a service of a particular class rather than a named service
• Search order - the order in which services of the same name are sorted for searching purposes
• Listeners - a list of the listeners allocated to this service
• Request handler - the request handler for this service
• Implementation package - the implementation package that provides the business functionality
• Status information - you can see the current status and the time of the last status change
• Status log - this supplies information about the most recent event that occurred on this service
• Custom configuration data - for more information see the section Configuration Information
• Description

Service display flters control how much service information you can see. These appear at the top of the services table. There are four service display filters:

• Service: to use this filter, specify the name of the service you want to view; you need only enter enough characters to identify the service uniquely
• Class
• Handler
• Package

Except for Service, each has three options

• None: choose this to see no services for this filter
• Some: choose this to see services that have a value for this filter
• All: choose this to see all services for this filter

For example, to see service details for services of class 1, choose Some in Service Display Filters Class; to see only services that do not have a request handler associated with them, choose None in Service Display Filters Handler; to see all services choose All in all three filters that have options and leave Service blank. Use all the filters in combination to achieve the maximum control over the level of detail you see.

When you first see the Services table, all the filters that have options are set to All and the Service filter is blank.

Configuration Information

You can use the Configuration Information field on the Add Service and Edit Service pages for configuration data specific to services. The only Configuration Information settings for services are for deployment services, the special services with Service Class “MF Deployment” which are used by the Interface Mapping Toolkit to deploy Web Services and J2EE EJBs.

The [MF client] settings provide configuration for MFCC when it is creating the deployment request.

The [destination] settings are used by mfdepinst when it creates service and package objects in the Directory Server while installing a deployment package (.car file). Note that these settings are only used when deployment is done via MFCS, using the IMTK or another deployment client. If you run mfdepinst manually from the command line to install a .car file, it is not invoked for a particular deployment service, so it has no deployment service configuration to consult.

[MF client]
scheme=protocol
URL=virtual-directory-name-1/mfdeploy.exe/virtual-directory-name-2
accept=request-data-type
[destination]
listener=listener-name
server=server-name

scheme

Specifies the protocol to use for the request.

Syntax:

scheme=protocol

Parameters:

Properties:

URL

Sets the base path portion of the request URL.

Syntax:

URL=virtual-directory-name-1/mfdeploy.exe/virtual-directory-name-2

Parameters:

Properties:

Comments:

You can have multiple deployment services under a single Web listener, directing deployment packages to different locations, by creating additional virtual directories in the listener’s configuration and specifying the appropriate directory here. For more information see the section Deployment Services and Listeners in the chapter Configuration.

accept

Tells MFCC what kind of request data this service accepts.

Syntax:

accept=request-data-type

Parameters:

Properties:

listener

Specifies the name of the listener which will own the new services. By default this is “Web Services”. You can set this value if you want to deploy services to a listener with a different name.

Syntax:

listener=listener-name

Properties:

Comments:

You can set this value if you want to deploy services to a listener with a different name.

server

Specifies the name of the server which will own the new services and packages. By default this is the server that the deployment service belongs to. You can set this value so that an enterprise server accepts deployment requests for services that will be deployed to a different enterprise server on the same system.

Syntax:

server=server-name

Properties:

Comments:

You can set this value so that an enterprise server accepts deployment requests for services that will be deployed to a different enterprise server on the same system.

What You Can Do

If you have Modify permission level or higher you can:

• Edit the attributes of a service
• Switch logging on or off for a service. When logging is on, the service's request and result blocks are written to the enterprise server's dump data set
• Change the status of a service between available and disabled

If you have Add/Delete permission level or higher you can also:

• Add a service
• Delete a simple service or operation
• Delete a service with operations. When you delete a service with operations you delete all the operations associated with it. You can also delete the packages associated with it

How to...

Implementation Packages

An implementation package defines the application that provides the business functionality.

The Packages Table

You can see the information held in the repository for packages by clicking Details against Packages in the table of servers on the Home page. The packages table is shown in Figure 8-2.

Figure 8-2: Packages Table

The information is as follows:

• Name – this is unique in an enterprise server
• Current status
• Status log – this supplies information about the most recent event that occurred on this package
• Package module – the name of the library containing the package, if it is part of a library
• IDT – the name of the interface definition table (IDT) for this package
• Package path – the location of the package module
• Custom configuration data - this field is not used
• Description

What You Can Do

If you have Modify permission level or higher you can:

• Edit the attributes of a package
• Change the status of a package between available and unavailable
• Associate a package with a service
• Disassociate a package from a service

If you have Add/Delete permission level or higher you can also:

• Add a package to an enterprise server
• Delete a package, as long as it is not associated with any service

Request Handlers

A request handler is software that receives a client request for access to the service, and translates the request into a form that the application providing the business functionality can understand. The following request handlers are provided with Enterprise Server:

• MFRHSOAP – handles requests that use SOAP (Simple Object Access Protocol). These are requests for Web services. They are coded in XML.
• MFRHBINP – handles binary requests made by the Micro Focus J2EE connector.

The Request Handlers Table

You can see the information held in the repository for request handlers by clicking Details against Request Handlers in the table of servers on the Home page. The request handlers table is shown in Figure 8-3.

Figure 8-3: Request Handlers Table

The information is as follows:

• Module name
• Module path
• Current status
• Status log – this supplies information about the most recent event that occurred on this request handler
• Custom configuration data - this field is not used
• Description

What You Can Do

If you have Modify permission level or higher you can:

• Edit the attributes of a request handler
• Change the status of a request handler between available and unavailable
• Associate a request handler with a service
• Disassociate a request handler from a service

If you have Add/Delete permission level or higher you can also:

• Add a request handler to an enterprise server
• Delete a request handler. You cannot delete MFRHBINP

How to...

Copyright © 2007 Micro Focus (IP) Ltd. All rights reserved.