Configuring Adapters and Gateways
The following topics provide an instructional overview for configuring gateways and native or non-native adapters.
Configuring In-Process Adapters and Gateways
When a native adapter or gateway runs exclusively in the same Java Virtual Machine (JVM) as the SAK, the adapter or gateway does not need its own port for communication. Examples of in-process adapters and gateways include a servlet running within a JSP application or a task processor. In these instances, the SAK must be able to locate the class files that are associated with the adapter or gateway.
To provide the required information, 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 base URI you entered when you started the administrator and the service name.
As you enter a value 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 delete the runtime service name, the service name you enter becomes the runtime service name. The runtime service name is prepended to the properties that are set. The properties starting with this name are used when the adapter or gateway is instantiated.
• The service class. This attribute identifies the class files used for the adapter or gateway.
• Adapter or gateway properties as described in the corresponding adapter guide or the help that is available from the Property Administration utility.
To configure an Info*Engine server to support in-process adapters, you must include the adapter class files in the codebase of the server. If the adapter class files are contained in the lib or classes directory within the codebase/WEB-INF directory, no changes are required.
No additional configuration is required for using the gateway in-process.
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.
Creating Adapter and Gateway Entries
To create an adapter or gateway entry in the LDAP directory, select the corresponding adapter or gateway from the Create Entry drop-down menu in the Info*Engine Property Administration utility. A window displaying the property form opens, with an asterisk (*) displayed next to required property fields. Depending on which adapter or gateway you are configuring, the form can contain additional properties that can be set. Use the help provided in the Property Administration utility and the corresponding adapter guide to determine which properties to actually set.
By default, the adapter forms usually supply the correct service class. Therefore, for in-process adapters and gateways, you only need to enter a unique name in the Service Name field and set other adapter properties as determined for your environment. For example, on the JNDI adapter form, you could enter values for the user, password, URL, drivers, and type of database you are connecting to.
The following example shows many of the fields on a sample JNDI form:
In this example, the ptcServiceName attribute and the Runtime Service Name values are initially set to “com.myCompany.myLocation.myHost.jndiAdapter”, which is the Service Name value. For out-of-process adapters, you must specify the host and port rather than the service class.
The form also shows that the Provider Url field must be filled in (as indicated by the asterisk).
Defining INSTANCE Names for Adapters
In conjunction with defining the conventions for how your site names Info*Engine components such as adapters and gateways, you must communicate to your user community which names they should use to access the adapters and gateways. These names are specified in the data value for the INSTANCE parameter on adapter webjects.
The Naming Service recognizes the following component name forms:
• A simple name as defined in the ptcServiceName attribute of the LDAP entry. This name can be used when the entry is in the Naming Service search path. For example if the ptcServiceName attribute is set to “com.myCompany.myHost.jdbcAdpt”, then the INSTANCE data value is the following:
com.myCompany.myHost.jdbcAdpt
• A fully-qualified distinguished name. This name can be used to locate a specific Info*Engine LDAP entry that is anywhere in the LDAP directory.
For example if the “com.myCompany.myHost.jdbcAdpt” entry is located at “dc=myHost,dc=myCompany,dc=com,ou=Applications,o=myCompany” then the distinguished name is used in the following form:
ptcServiceName=com.myCompany.myHost.jdbcAdpt,dc=myHost,dc=myCompany,
dc=com,ou=Applications,o=myCompany
dc=com,ou=Applications,o=myCompany
• A domain-based reference name in the form:
ptcServiceName@dc_attributes
In this format, ptcServiceName is the value of the ptcServiceName attribute and dc_attributes are the dc attributes that make up the domain location of the LDAP entry, where each attribute is separated from the next attribute using a period.
 | The domain-based reference name can only be used when the LDAP directory that has the Info*Engine entries is constructed using dc=com as a root-level directory or when the Naming Service .serviceDomainBaseproperty is set to include those attributes beyond the domain that are used in the distinguished name of the entry. |
For example, if the ptcServiceName attribute value is “com.myCompany.myHost.jdbcAdpt” and the entry is located in the “dc=myHost,dc=myCompany,dc=com,ou=Applications,o=myCompany” branch, then the following domain-based reference name could only be used if the .serviceDomainBaseproperty is set to “ou=Applications,o=myCompany”:
com.myCompany.myHost.jdbcAdpt@myHost.myCompany.com
Use the Info*Engine Property Administration utility to set the .serviceDomainBaseproperty. For more information, see the property help in theProperty Administration utility.
Usually, entering the simple name that is defined in ptcServiceName attribute works well for the INSTANCE parameter value. However, you must look at how you are constructing the Info*Engine LDAP entries and where the entries are located relative to the Naming Service search path to determine the best strategy for your site.