Configuring Out-of-Process Adapters and Gateways
When a native adapter or gateway is configured to run in its own Java Virtual Machine (JVM), the adapter or gateway needs its own communication port and must be started separately. In addition, the Naming Service must be able to locate the adapter or gateway.
To provide the required information to the Naming Service, you must include the following attributes in the LDAP entry for the adapter or gateway:
• A service name for the adapter or gateway. This is usually the name that users enter on the webject INSTANCE parameter to access the adapter or gateway.
The name you enter should be unique within the Naming Service search base (unless you are providing redundant services for load balancing or failures). To name your adapter or gateway service, use the LDAP naming convention set up by your site. The convention that is used by default is described in
Info*Engine LDAP Directories.
• The distinguished name of the LDAP entry.
By default, the Info*Engine Property Administration utility suggests a distinguished name that is based on the service name and the base URI you entered when you logged into the utility. As you type in the Service Name field, the ptcServiceName attribute in the distinguished name is updated to include the service name changes. To ensure that the correct LDAP entry is created for the service, you should not manually modify the ptcServiceName attribute. If you want the entry to reside at a LDAP directory location that is different from the default location, you can modify the other attributes in the distinguished name.
• The runtime service name.
Initially, the Property Administration utility populates the Runtime Service Name field with the same name it enters in the Service Name field. If you change the runtime service name, the service name you enter becomes the runtime service name. The runtime service name is the name prepended to the properties that are set and the name you use to start the adapter or gateway.
• The host where the adapter or gateway resides.
• The port number or port range associated with the host.
If specifying a port range, separate the lower port number and upper port number with a dash (for example 1001-1005). Upon startup, an out-of-process adapter selects the first available port within the port range to use. Info*Engine requests are then load-balanced across ports within the configured ranges that are in use.
• The serialization type that Info*Engine should use when passing data to the adapter. By default, Info*Engine components use Java serialization. Java serialization preserves data type information so that the data can be easily manipulated from within an Info*Engine custom application, JSP, or task.
The only time you need to change this type is when an out-of-process adapter that you are configuring is a pre-Info*Engine Release 6 adapter or is a custom adapter that only accepts XML. In these cases, set the Serialization Type field to xml (which sets the ptcObjectSerializationType attribute to text/xml). Otherwise, you can let the attribute default to java (which sets the attribute to application/java-serialization-object).
• The adapter or gateway properties as described in the corresponding adapter guide or in the help that is available from the Property Administration utility.
To configure multiple components that use the same set of properties other than the host and port, you can add multiple host and port pairs in one LDAP entry, or you can configure a single host and a port range. When that entry is used, Info*Engine load balances across adapters, listening for requests on the configured network addresses.
You can also create some adapter services, such as the Windchill adapter service, so that they can be run both as an in-process and out-of-process adapter. When you include both the service class for the in-process adapter and the host and port for the out-of-process adapter on the adapter form, Info*Engine determines when the adapter can be run in process and does so whenever possible. If you want to define which Info*Engine services can call the adapter service in process, you can enter the distinguished name of each service in the Co-Resident Services field.
To automatically start an out-of-process adapter when the Info*Engine Naming Service starts, you should create a startup script and name the script to an Naming Service Launch field on the Naming Service form. In the -DmyName argument of the startup command, use the runtime service name you supplied in the adapter LDAP directory entry.
If the adapter or gateway is not on the same hardware system as the Naming Service, you must determine how you are going to ensure that the adapter or gateway is running when requests for it are made.