Skip Headers

Oracle9iAS InterConnect Adapter for HTTP Installation and User's Guide
Release 2 (9.0.2)

Part Number A95445-01
Go To Documentation Library
Home
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

2
Installation and Configuration

This chapter describes Hypertext Transfer Protocol (HTTP) adapter installation and configuration.

This chapter contains these topics:

Installing HTTP Adapter

This section contains these topics:

Preinstallation Tasks

The HTTP adapter must be installed in one of the following Oracle homes:

Consult the Oracle9i Application Server Installation Guide before proceeding with HTTP adapter installation. This guide includes the following information:

Installation Tasks

To install the HTTP adapter:

  1. Click Next on the Welcome screen.

    The File Locations screen appears.

  2. Enter the following information in the Destination fields:

  3. Click Next.

    The Installation Types screen appears.

  4. Select Oracle9iAS InterConnect Adapters and click Next.

    The Available Product Components screen appears.

  5. Select Oracle9iAS InterConnect HTTP Adapter and click Next.

  6. If the HTTP adapter is not being installed on the same computer as Oracle9iAS InterConnect and another adapter is not installed in the current Oracle home, the Oracle9iAS InterConnect Hub Database screen appears. Enter the following information about Oracle9iAS InterConnect:

    • Host Name--The hostname of the computer on which Oracle9iAS InterConnect is installed

    • Port Number--The port number of the computer

    • Database SID--The system identifier (SID) of the Oracle9iAS InterConnect Oracle9iAS Metadata Repository

    • Password--The password for the Oracle9iAS Metadata Repository schema

    The Oracle9iAS Metadata Repository stores metadata used by Oracle9iAS InterConnect to coordinate communication between components.

  7. Click Next.

    The Oracle9iAS InterConnect HTTP Adapter Configuration screen appears.

  8. Enter the name of the application associated with the HTTP adapter. White spaces or blanks are not allowed. This is the same application name created or to be created in iStudio.

  9. Click Next.

    The Oracle9iAS InterConnect HTTP Adapter usage screen appears.

  10. Select one of the following options and go to the step specified to enable the sending and receiving of messages, the sending of messages only, or the receiving of messages only from an external data source, such as an HTTP server. You can change the values for these selections later by editing parameter settings in the adapter.ini file.

    If You Select... Then Click Next and Go to Step...

    Configure for both sending and receiving messages

    11

    Configure for sending messages ONLY

    11

    Configure for receiving messages ONLY

    13

  11. Enter the following information in the Oracle9iAS InterConnect HTTP Adapter Configuration - Configure sending endpoint information screen:

    • URL--The URL of the outgoing HTTP server to which Oracle9iAS InterConnect sends messages. Enter the URL as follows:

      http://hostname:port/path
      
  12. Click Next.

    The installation screen that appears next is based on the selection you made in Step 10:

    If You Selected... Then Go to Step...

    Configure for both sending and receiving messages

    13

    Configure for sending messages ONLY

    15

  13. Enter the following information in the Oracle9iAS InterConnect HTTP Adapter Configuration - Configure receiving endpoint information screen:

    • Hostname--The hostname of the HTTP server from which Oracle9iAS InterConnect receives messages.

    • Port Number--The port number of the HTTP server.

  14. Click Next.

  15. Complete any other fields for other components selected for installation, such as other adapters.

    When finished, the Summary screen appears.

  16. Select Install to install the HTTP adapter. The adapter is installed in the following directory:

    Platform Directory

    Windows

    %ORACLE_HOME%\oai\9.0.2\adapters\Application

    UNIX

    $ORACLE_HOME/oai/9.0.2/adapters/Application

    Application is the value you specified in Step 8. A webapps subdirectory is created in the Application directory identified in Step 16. webapps includes the following files created for the HTTP application:

    • An EAR file (oai.ear)

    • A web.xml file located in the WEB-INF directory

    • An application.xml file located in the META-INF directory

Postinstallation Tasks

HTTP adapter installation creates an adapter.ini file that consists of configuration parameters read by the HTTP adapter at startup. The configuration parameter settings are appropriate for most HTTP application environments. If you want to customize some adapter.ini file parameter settings for the HTTP application, see the following sections:

Customizing the Payload Datatype

Payload data is the data sent between applications. If you want to change the payload datatype from the default of XML to the data definition description language (D3L), edit the following parameters in the adapter.ini file.

To customize the payload datatype:

  1. Set the ota.type parameter to the payload type D3L. For example:

    ota.type=D3L
    
  2. Copy the D3L XML files associated with the HTTP application to the directory in which the adapter.ini file is located.

  3. Set the ota.d3ls parameter to specify the D3L files associated with the HTTP application. For example:

    ota.d3ls=person1.xml,person2.xml
    

    See Also:

    The following parameter descriptions for additional information:

Customizing the Sending Endpoints

If you want to customize the behavior of the sending endpoints (destinations) for messages, edit the following parameter in the adapter.ini file.

To customize the sending endpoints:

  1. Set the http.sender.timeout parameter to the timeout interval in milliseconds for HTTP connections. This parameter automatically defaults to a value of 60000 during installation. For example:

    http.sender.timeout=10000
    

    See Also:

    http.sender.timeout parameter description for additional information

Customizing the Authentication Scheme

If you want to use an authentication scheme, edit the following parameters in the adapter.ini file. These parameters are not automatically set to default values during installation.

To customize the authentication scheme:

  1. Set the http.sender.authtype parameter to the authentication type to use. For example:

    http.sender.authtype=basic
    
  2. Set the http.sender.realm parameter to the realm for the authentication scheme. For example:

    http.sender.realm=ipt
    
  3. Set the http.sender.username parameter to the authentication username. For example:

    http.sender.username=joe
    
  4. Set the http.sender.password parameter to the authentication password. For example:

    http.sender.password=100100101
    

    See Also:

    The following parameter descriptions for additional information:

Customizing a Proxy Host

If you want to use a proxy host, edit the following parameters in the adapter.ini file. These parameters are not automatically set to default values during installation.

To customize a proxy host:

  1. Set the http.sender.proxy_host parameter to the hostname of the proxy server. For example:

    http.sender.proxy_host=www-proxy.foo.com
    
  2. Set the http.sender.proxy_port parameter to the port number of the proxy server. For example:

    http.sender.proxy_port=80
    

    See Also:

    The following parameter descriptions for additional information:

Customizing a Secure Socket Layer Environment

If you want to use the secure socket layer (SSL) environment for sending messages, edit the following parameters in the adapter.ini file. These parameters are not automatically set to default values during installation.

To customize a secure socket layer environment:

  1. Set the http.sender.wallet_location parameter to the directory path and name of the wallet file. For example:

    http.sender.wallet_location=/private/foo/certdb.txt
    
  2. Set the http.sender.wallet_password parameter to the Oracle Wallet Manager password. For example:

    http.sender.wallet_password=4341193845566
    
  3. Set the http.sender.cipher_suites parameter to the cipher suites used in the secure connection. For example:

    http.sender.cipher_suites=SSL_RSA_WITH_NULL_SHA,SSL_RSA_WITH_3DES_EDE_CBC_
    SHA
    

    See Also:

    The following parameter descriptions for additional information:

Customizing the Receiving Endpoints

If you want to customize the behavior of receiving endpoint messages, edit the following parameter in the adapter.ini file.

To customize the receiving endpoints:

  1. Set the http.receiver.registry_port parameter to the remote method invocation (RMI) registry port for communicating with the servlet. This parameter automatically defaults to a value of 9901 during installation. For example:

    http.receiver.registry_port=3500
    

    See Also:

    http.receiver.registry_port parameter description for additional information

Manually Deploying an EAR File

If the Oracle9iAS Containers for J2EE (OC4J) is installed on a separate computer from the HTTP adapter, you must manually:

To manually deploy an EAR file:

  1. Go to the following directory:

    cd myHTTPapphome
    

    where myHTTPapphome is the directory in which the HTTP application is installed and the value you defined in Step 8.

  2. Extract all files from the oai.ear file:

    jar xvf oai.ear 
    
  3. Extract all files from the oai.war file:

    jar xvf oai.war
    
  4. Go to the following directory:

    cd WEB-INF
    
  5. Use a text editor to open the web.xml file:

    web.xml specifies the RMI information that must match with the setting in the adapter.ini file. For example, rmiHost must match the hostname of the computer on which the HTTP adapter is installed. The HTTP adapter serves as the RMI server. The transport servlet makes an RMI call to submit the requests sent by the external application. You can also edit the logging options that are turned off by default.

    The following web.xml file shows the rmiHost parameter with a computer hostname setting of prodserver10:

    <init-param>
      <param-name>rmiHost</param-name>
      <param-value>prodserver10</param-value>
    </init-param>
    <init-param>
      <param-name>rmiPort</param-name>
      <param-value>9901</param-value>
    </init-param>
    <init-param>
      <param-name>instanceName</param-name>
      <param-value>oai</param-value>
    </init-param>
    <!-- set the following parameters if logging is needed. -->
    <init-param>
      <param-name>isLogOn</param-name>
      <!-- enter true/false -->
      <param-value>false</param-value>
    </init-param>
    <init-param>
      <param-name>logDir</param-name>
      <!-- directory where log file is placed. -->
      <param-value></param-value>
    </init-param>
    <init-param>
      <param-name>logLevel</param-name>
      <!-- choose one of the levels: debug, status, or  error -->
      <param-value></param-value>
     </init-param>
    
  6. Save the changes and exit the file.

  7. Return to the following directory:

    cd myHttpApphome
    
  8. Restore the oai.war and oai.ear files:

    jar cvf oai.war WEB-INF
    jar cvf oai.ear META-INF/ oai.war
    
  9. See the Oracle9i Application Server Administrator's Guide for instructions on using the Distributed Configuration Management (DCM) command line utility to deploy the EAR file.

HTTP Adapter Configuration Parameters

Table 2-2, Table 2-3, and Table 2-4 describe executable files, configuration files, and directories. These files and directories are accessible from the directory shown in Table 2-1:

Table 2-1 HTTP Adapter Directory
On... Go to...

UNIX

$ORACLE_HOME/oai/9.0.2/adapters/Application

Windows

%ORACLE_HOME%\oai\9.0.2\adapters\Application

Table 2-2 HTTP Executable Files
File Description

start.bat (Windows) start (UNIX)

Takes no parameters, starts the adapter

stop.bat (Windows) stop (UNIX)

Takes no parameters; stops the adapter

ignoreerrors.bat (Windows) ignoreErrors (UNIX)

If an argument is specified, then the given error code is ignored:

ignoreerrors errorCodeToBeIgnored

If no argument is specified, then all error codes specified in the ErrorCodes.ini file are ignored:

ignoreerrors

See Also:

"HTTP Error Codes"

Table 2-3 HTTP Configuration Files
File Description

ErrorCodes.ini (Windows and UNIX)

Should contain one error code for each line

adapter.ini (Windows and UNIX)

Consists of all the initialization parameters that the adapter reads at startup

See Also:

Appendix A, "adapter.ini Example File"

Table 2-4 HTTP Directories
Directory Description

persistence

The messages are persisted (made available) in this directory. Do not edit this directory or its contents.

logs

The logging of adapter activity is done in subdirectories of the logs directory. Subdirectory names take the following form:

timestamp_in_milliseconds

Each time the adapter is run, a new subdirectory is created in which logging is done in an oailog.txt file.

adapter.ini Initialization Parameter File

This section contains these topics:

Agent Connection Parameters

The agent component of the HTTP adapter reads the adapter.ini file at runtime to access HTTP adapter parameter configuration information. Table 2-5 lists the parameter name, a description for each parameter, the possible and default values, and an example.

Table 2-5 Agent Connection Parameters
Parameter Description Example

application

Specifies the name of the application to which this adapter connects. This must match with the name specified in iStudio during creation of metadata. Use any alphanumeric string. There is no default value.

application=aqapp

partition

Specifies the partition this adapter handles as specified in iStudio. Any alphanumeric string is a possible value. There is no default value.

partition=germany

instance_number

Specifies the instance number to which this adapter corresponds. Specify a value only if you want to have multiple adapter instances for the given application with the given partition. Possible values are any integer greater than or equal to 1. There is no default value.

instance_number=1

agent_log_level

Specifies the amount of logging necessary. Possible values are:

0=errors only

1=status and errors

2=trace, status, and errors

The default value is 1.

agent_log_level=2

agent_subscriber_name

Specifies the subscriber name used when this adapter registers its subscription. The possible value is a valid Oracle Advanced Queue subscriber name. There is no default value.

agent_subscriber_name=httpapp

agent_message_selector

Specifies conditions for message selection when registering its subscription with the hub. The possible value is a valid Oracle Advanced Queue message selector string. There is no default value.

agent_message_selector=recipient_list, like '%,aqapp,%'

agent_reply_subscriber_name

Specifies the subscriber name used when multiple adapter instances for the given application with the given partition are used. This parameter is optional if only one instance is running. The possible value is the application name (parameter:application) concatenated with the instance number (parameter:instance_number). There is no default value.

If application=httpapp and instance_number=2, then agent_reply_subscriber_name=httpapp2

agent_reply_message_selector

Used only if multiple adapter instances exist for the given application with the given partition. The possible value is a string built using the concatenated application name (parameter:application) with the instance number (parameter:instance_number). There is no default value.

If application=httpapp and instance_number=2, then agent_reply_message_selector=recipient_list, like '%,httpapp2,%'

agent_tracking_enabled

Specifies if message tracking is enabled. Set this parameter to false to turn off all tracking of messages. Set this parameter to true to track messages with tracking fields set in iStudio. Possible values are true or false. The default value is true.

agent_tracking_enabled=true

agent_throughput_measurement_enabled

Specifies if the throughput measurement is enabled. Set this parameter to true to turn on all throughput measurements. Possible values are true or false. The default value is true.

agent_throughput_measurement_enabled=true

agent_use_custom_hub_dtd

Specifies whether to use a custom document type definition (DTD) for the common view message when handing it to the hub (the repository in which metadata is stored). By default, adapters use an Oracle9iAS InterConnect-specific DTD for all messages sent to the hub, as other Oracle9iAS InterConnect adapters retrieve the messages from the hub and know how to interpret them.

Set this parameter to true if for every message, the DTD imported for the message of the common view is used instead of the Oracle9iAS InterConnect DTD. Only set this parameter to true if an Oracle9iAS InterConnect adapter is not receiving the messages from the hub. Possible values are true or false. There is no default value.

agent_use_custom_hub_dtd=false

agent_metadata_caching

Specifies the metadata caching algorithm. Possible values are:

  • startup--Cache everything at startup. This may take a while if a lot of metadata is in the repository.

  • demand--Cache metadata as it is used.

  • none--No caching. This slows down performance.

The default value is demand.

agent_metadata_caching=demand

agent_dvm_table_caching

Specifies the domain value mapping (DVM) table caching algorithm. Possible values are:

  • startup--Cache all DVM tables at startup. This may take a while if many tables are in the repository.

  • demand--Cache tables as they are used.

  • none--No caching. This slows down performance.

The default value is demand.

agent_dvm_table_caching=demand

agent_lookup_table_caching

Specifies the lookup table caching algorithm. Possible values are:

  • startup--Cache all lookup tables at startup. This may take a while if many tables are in the repository.

  • demand--Cache tables as they are used.

  • none--No caching. This slows down performance.

The default value is demand.

agent_lookup_table_caching=demand

agent_delete_file_cache_at_startup

With any of the agent caching methods enabled, metadata from the repository is cached locally on the file system. Set this parameter to true to delete all cached metadata on startup. Possible values are true or false. The default value is false.

Note: After changing metadata or DVM tables for this adapter in iStudio, you must delete the cache to guarantee access to new metadata or table information.

agent_delete_file_cache_at_startup=false

agent_max_ao_cache_size

Specifies the maximum number of application objects' metadata to cache. Possible values are any integer greater than or equal to 1. The default value is 200.

agent_max_ao_cache_size=200

agent_max_co_cache_size

Specifies the maximum number of common objects' metadata to cache. Possible values are any integer greater than or equal to 1. The default value is 100.

agent_max_co_cache_size=100

agent_max_message_metadata_cache_size

Specifies the maximum number of messages' metadata (publish/subscribe and invoke/implement) to cache. Possible values are any integer greater than or equal to 1. The default value is 200.

agent_max_message_metadata_cache_size=200

agent_max_dvm_table_cache_size

Specifies the maximum number of DVM tables to cache. Possible values are any integer greater than or equal to 1. The default value is 200.

agent_max_dvm_table_cache_size=200

agent_max_lookup_table_cache_size

Specifies the maximum number of lookup tables to cache. Possible values are any integer greater than or equal to 1. The default value is 200.

agent_max_lookup_table_cache_size=200

agent_max_queue_size

Specifies the maximum size to which internal Oracle9iAS InterConnect message queues can grow. Possible values are any integer greater than or equal to 1. The default value is 1000.

agent_max_queue_size=1000

agent_persistence_queue_size

Specifies the maximum size to which internal Oracle9iAS InterConnect persistence queues can grow. Possible values are any integer greater than or equal to 1. The default value is 1000.

agent_persistence_queue_size=1000

agent_persistence_cleanup_interval

Specifies how often to run the persistence cleaner thread (in milliseconds). Possible values are any integer greater than or equal to 30000. The default value is 60000.

agent_persistence_cleanup_interval=60000

agent_persistence_retry_interval

Specifies how often the persistence thread retries when it fails to send an Oracle9iAS InterConnect message. Possible values are any integer greater than or equal to 5000. The default value is 60000.

agent_persistence_retry_interval=60000

service_path

Windows only. Specifies the value to which to set the environment variable PATH. The PATH variable is set to the specified value before forking the Java VM. Typically, list all directories here that contain all necessary DLLs. Possible values are the valid PATH environment variable setting. There is no default value.

service_path=%JREHOME%\bin;D:\oracle\ora902\bin

service_classpath

Windows only. Specifies the class path used by the adapter Java VM. If a custom adapter is developed and, as a result, the adapter is to pick up any additional jars, add the jars to the existing set of jars being picked up. Possible values are the valid class path. There is no default value.

service_classpath=D:\oracle\
ora902\oai\902\lib\
oai.jar;%JREHOME%\lib\rt.jar;D:\oracle\ora902\jdbc\classes12.zip

service_class

The entry class for the Windows NT service. A possible value is oracle/oai/agent/service/AgentService. There is no default value.

service_class=oracle/oai/agent/ service/AgentService

service_max_java_stack_size

Windows only. Specifies the maximum size to which the Java VM's stack can grow. Possible values are the valid Java VM maximum native stack size. The default value is the default for the Java VM.

service_max_java_stack_size=409600

service_max_native_stack_size

Windows only. Specifies the maximum size to which the Java VM's native stack can grow. Possible values are the valid Java VM maximum native stack size. The default value is the default for the Java VM.

service_max_native_stack_size=131072

service_min_heap_size

Windows only. Specifies the minimum heap size for the adapter Java VM. Possible values are the valid Java VM heap sizes. The default value is 536870912.

service_min_heap_size=536870912

service_max_heap_size

Windows only. Specifies the maximum heap size for the adapter Java VM. Possible values are any valid Java VM heap sizes. The default value is 536870912.

service_max_heap_size=536870912

service_num_vm_args

Windows only. Specifies the number of service_vm_argnumber parameters specified. Possible values are the number of service_vm_argnumber parameters. There is no default value.

service_num_vm_args=1

service_vm_argnumber

Windows only. Specifies any additional arguments to the Java VM. For example, to retrieve line numbers in any of the stack traces, set service_vm_arg1=java.compiler=NONE. If a list of arguments to specify exists, use multiple parameters as shown in the example by incrementing the last digit starting with 1. Be sure to set service_num_vm_args correctly. Possible values are any valid Java VM arguments. There is no default value.

service_vm_arg1=java.compiler=NONE

service_vm_arg2=oai.adapter=database

HTTP Adapter-Specific Parameters

Table 2-6 lists the parameters specific to the HTTP adapter.

Table 2-6 HTTP Adapter-Specific Values
Parameter Description Example

bridge_class

Specifies the entry class for the HTTP adapter. A value must be specified and cannot be modified later. A possible value is oracle.oai.agent.adapter.technology.TechBridge. There is no default value.

bridge_class=oracle.oai.agent.adapter.technology.TechBridge

ota.send.endpoint

Defines the sending endpoint URL for the HTTP adapter. There is no default value. The URL is of the form:

http(s)://hostname:port/path

ota.send.endpoint=http://site.com:8888/servlet/inbound

ota.receive. endpoint

Defines the receiving endpoint URL for the HTTP adapter. There is no default value. The URL is of the form:

http(s)://hostname:port/path

ota.receive.endpoint= http://site.com:8888/ servlet/inbound

ota.type

Defines the message payload type the HTTP adapter handles for both incoming and outgoing messages. The options are XML, XML_NVP, or D3L. The default value is XML.

ota.type=XML

http.sender.timeout

Times out an HTTP connection. The unit is in milliseconds. The default is set to 60000 milliseconds (60 seconds).

http.sender.timeout= 10000

(Sets timeout to 10 seconds)

http.sender.authtype

Set if authentication is needed. The valid options are basic or digest. There is no default value.

http.sender.authtype= basic

http.sender.realm

Specifies the realm for the authentication scheme. There is no default value.

http.sender.realm=ipt

http.sender.username

Specifies the authentication username. There is no default value.

http.sender.username= joe

http.sender.password

Specifies the password used in the sender.password authentication. There is no default value. This password can also be encrypted by running the encrypt tool and renaming this parameter to encrypted_http.sender.password.

See Also: "How do I make the adapter.ini file password parameters secure?" for instructions on encrypting the user password

http.sender.password= httpuser

http.sender.proxy_host

Specifies the proxy hostname. There is no default value.

http.sender.proxy_host=www-proxy.foo.com

http.sender.proxy_port

Specifies the port number for the proxy host. This is needed if the proxy host is set. There is no default value.

http.sender.proxy_port=80

http.sender.wallet_location

Needed if SSL is used. This specifies the path and name of the wallet file. There is no default value.

http.sender.wallet_location=/private/foo/ certdb.txt

http.sender.wallet_password

Needed if SSL is used. This specifies the password for the Oracle Wallet Manager. There is no default value. This password can also be encrypted by running the encrypt tool and renaming this parameter to encrypted_http.sender.wallet_password.

See Also: "How do I make the adapter.ini file password parameters secure?" for instructions on encrypting the wallet password

http.sender.wallet_password=walletuser

http.sender.cipher_suites

Optional parameter for choosing the cipher suites. The selections are:

SSL_RSA_WITH_3DES_EDE_CBC_SHA

SSL_RSA_WITH_RC4_128_SHA

SSL_RSA_WITH_RC4_128_MD5

SSL_DH_anon_WITH_3DES_EDE_CBC_SHA

SSL_DH_anon_WITH_RC4_128_MD5

SSL_DH_anon_WITH_DES_CBC_SHA

SSL_RSA_WITH_DES_CBC_SHA

SSL_RSA_EXPORT_WITH_RC4_40_MD5

SSL_RSA_EXPORT_WITH_DES40_CBC_SHA

SSL_DH_anon_EXPORT_WITH_RC4_40_MD5

SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA

SSL_RSA_WITH_NULL_SHA

SSL_RSA_WITH_NULL_MD5

http.sender.cipher_suites=SSL_RSA_WITH_NULL_SHA,SSL_RSA_WITH_3DES_EDE_CBC_SHA

http.receiver.registry_port

Specifies the RMI port used by the HTTP receiver. The default is 9901.

http.receiver.registry_port=9901

http.receiver. instance_name

Specifies the instance name of the HTTP receiver. The default is oai. If the default value is not used, the instanceName of the initial parameter of the transport servlet must be modified to match this instance name.

http.receiver.instance_name=oai

http.receiver. customized_class

Specifies the class name for customizing the HTTP response.

http.receiver. customized_class=MyBanner

ota.d3ls

Specifies the list of D3L XML files used by this bridge. Each business event handled by the bridge must have its own D3L XML file. When a new D3L XML file is imported in iStudio for use by an application using the HTTP adapter, the parameter must be updated and the HTTP adapter restarted.

ota.d3ls=person.xml, person1.xml


Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Table Of Contents
Contents
Go To Index
Index