Copyright © 2014 TIBCO Software Inc. All Rights Reserved


Chapter 2 Creating a TIBCO Silver Fabric Enabler for TIBCO API Exchange Gateway Stack : Creating TIBCO® API Exchange Gateway Components

Creating TIBCO® API Exchange Gateway Components
Configuration of the Component created with TIBCO Silver Fabric Enabler for TIBCO API Exchange Gateway determines how the Distribution is published to the Engines.
TIBCO® API Exchange Gateway Distribution for TIBCO Silver® Fabric contains the expanded product installation used to publish and run any and all of the following:
TIBCO® API Exchange Gateway - Configuration GUI (asg-configui)
TIBCO® API Exchange Gateway - Core Engine (asg-core)
TIBCO® API Exchange Gateway - Core Engine (asg-core) with the Cache Agent Enabled (asg-caching-core)
TIBCO® API Exchange Gateway - Global Throttle Manager (asg-gtm)
TIBCO® API Exchange Gateway - Cache Agent (asg-cache)
TIBCO® API Exchange Gateway - Cleanup Agent (asg-cache-cleanup)
TIBCO® API Exchange Gateway - APIX Central Logger (asg-cl)
A limited set of installation configurations are presented by the GUI of the TIBCO Silver Fabric Component Wizard, but you can pass any command line options exposed by TIBCO® API Exchange Gateway Engine or upload a startup property file (TRA file) with your custom configurations.
To create and configure a component, perform the relevant tasks according to the type of TIBCO® API Exchange Gateway Engine you will create:
Publish the TIBCO® API Exchange Gateway component after you complete these tasks and at runtime, access TIBCO Configuration GUI, using the TIBCO Silver Fabric VirtualRouter address: http://Virtualrouter:9200/ConfigUI/
or directly with the Engine URL: http://SilverFabricEngine:9200/ConfigUI/
Task A Create a TIBCO® API Exchange Gateway Component
1.
In the TIBCO Silver® Fabric Administration Tool, select Stacks > Components.
2.
On the Components page, select Create New TIBCO® API Exchange Gateway from the Global Actions drop-down list as shown below.
Figure 1 Creating a TIBCO® API Exchange Gateway Component
3.
Figure 2 Configuring General Properties
4.
Select a version of each of the installed distributions. It is generally a good practice to use the latest version of a product distribution.
Refer to the TIBCO Silver® Fabric Enabler for TIBCO® API Exchange Gateway Readme for more information on supported distributions.
If there are multiple product distribution versions which are displayed then they are compatible with the component being defined.
Figure 3 Choosing TIBCO Product Distribution Versions
Make sure that the TIBCO_RV_distribution is present as is shown above.
TIBCO Rendezvous must be published with the TIBCO® API Exchange Gateway Distribution for TIBCO Silver® Fabric to provide messaging.
5.
Click the Next button TIBCO API Exchange Gateway: Configuration User Interface or Engine panel is displayed as is shown next in Task B, Set Enabler to launch Configuration User Interface or Engine.
 
Task B Set Enabler to launch Configuration User Interface or Engine
The TIBCO® API Exchange Gateway: Configuration User Interface or Engine page and each of the configuration parameters are described here. Enter appropriate values for each field as applicable.
Figure 4 TIBCO API Exchange Gateway: Configuration User Interface or Engine page
Enabler will launch - The "Enabler will launch" parameter determines whether this component will publish and install the TIBCO® API Exchange Gateway Configuration UI or run one of its Engines or Agents. Another option allows for manual testing of an Engine or Agent after configuration and installation.
Configuration UI - enables component configuration of the TIBCO® API Exchange Gateway User Interface.
Engine - enables component configuration of the TIBCO® API Exchange Gateway Engines/Agents and directly running that Engine/Agent when published and run in a Stack.
Core Engine (asg-core)
Core Engine in Cache Agent Enabled mode (asg-caching-core)
Global Throttle Manager (asg-gtm)
Cache Agent (asg-cache)
Cache Cleanup Agent (asg-cache-cleanup)
Central Logger with Database (asg-cl)
Install and configure without running to allow manual test of engine parameters - enables configuration and publishing of the TIBCO® API Exchange Gateway Engine to the TIBCO Silver Fabric Engine without automatically running the published Engine or Agent.
The selected Enabler will launch option determines what Component Wizard pages are displayed next.
Configuration directory path - When empty the location is the value of the runtime variable: TIBCO_HOME_CFGMGMT_DIR (set to ${ENGINE_WORK_DIR}/cfg_data To set a value other than the default simply enter a relative directory path such as: usr/myname/someDirectory
Change parameters - When this checkbox is selected the Logging Level and the HTTP Channel Base Port parameter values will apply. When this checkbox is not checked these parameter values will not be changed regardless of what values are input in the HTTP Channel Base Port fields below.
Logging Level - The logging level can be set to Debug (0), Info (1), Warning (2), Error (3), No Logging (4).
Façade HTTP Channel Base Port  / Façade HTTPS Channel Base Port - The client facing HTTP /HTTPS (SSL) base port starting point. This value is used as the reference so additional Engine instances derived from the same Component on the same machine get incremented HTTP/HTTPS port values to avoid port conflict. Refer to the TIBCO API Exchange Gateway User’s Guide for more information about use of the ports.
OAuth HTTP Channel Base Port  / OAuth HTTPS Channel Base Port - TIBCO API Exchange Gateway OAuth Server HTTP /HTTPS (SSL) base port starting point. This value is used as the reference so additional Engine instances derived from the same Component on the same machine get incremented OAuth HTTP/HTTPS port values to avoid port conflict. Refer to the TIBCO API Exchange Gateway User’s Guide for information about use of OAuth Server.
The next Component Wizard page displayed depends on the selection chosen in the "Enabler will launch" drop down selector.
For Components that will instantiate TIBCO® API Exchange Gateway Configuration UI see Configure TIBCO® API Exchange Gateway Configuration UI
For Components that will instantiate a TIBCO® API Exchange Gateway Engine skip to Configure the Parameters Used to Launch asg-engine
For Components that will instantiate TIBCO® API Exchange Gateway Engines without running them automatically skip to Task I, Configure TIBCO® API Exchange Gateway Running Conditions
Task C Configure TIBCO® API Exchange Gateway Configuration UI
The TIBCO API Exchange Gateway: User Interface Configuration page enables specification of Configuration UI administrator user name, password, and the HTTP Base Port.
Figure 5 TIBCO API Exchange Gateway: User Interface Configuration
The HTTP Base Port setting will be the port value of the first instance of TIBCO API Exchange Gateway User Interface installed. To avoid HTTP port conflicts when more than one TIBCO® API Exchange Gateway application is running on the same machine, TIBCO Silver® Fabric Enabler for TIBCO® API Exchange Gateway automatically increments the port as follows:
HTTP Base Port + EngineInstanceValue
Where the EngineInstanceValue is the Engine number where the application is running. For example on a dual-core machine, the default number of Engines is two (one per core). The first EngineInstanceValue will have a value of zero, the second will have a value of one.
Continue with the configuration of TIBCO API Exchange Gateway Configuration UI and Core Engine Settings
Task D TIBCO API Exchange Gateway Configuration UI and Core Engine Settings
Set up the Configuration UI Server or the Core Engine for reporting, facade and target JMS transport messaging, JMS delivery mode and JMS acknowledgement mode.
Enable Reporting - Enable reporting (event messaging) with a Central Logger. When the Enable Reporting checkbox is selected a Central Logger Component must be set as a dependency for the Configuration UI Component and it must be present in the Stack.
When this is checked the Component Wizard display another page to select either TIBCO Rendezvous or JMS for the "Log Reporting Messaging Transport Type".
Figure 6 Core Engine Settings "Set up the core engine for API Exchange component"page
 
Enabler Facade/Target JMS Transport - Leave this checkbox unselected to use TIBCO Rendezvous as the default messaging transport between component servers. When Rendezvous is the preferred messaging transport no further messaging configuration is necessary.
Select the checkbox to enable and configure JMS transport as SOAP/JMS or JMS/XML as ESB channels for the façade and target messaging transports.
Enabling use of Facade/Target JMS Transport will expose JMS Delivery Mode options, JMS Acknowledgement Mode options, and four additional Component Wizard configuration pages for configuring SOAP/JMS Facade Transport, ESB Facade Transport, SOAP/JMS Target Transport, and ESB Target Transport.
JMS Delivery Mode - Select a JMS delivery mode for TIBCO API Exchange Gateway servers. The delivery mode may be NON_PERSISTENT, PERSISTENT, or RELIABLE as is described in the table below:
RELIABLE (requires use of TIBCO Enterprise Message Service)
 
JMS Acknowledgment Mode - consult the following table
NO_ACKNOWLEDGE (requires use of TIBCO Enterprise Message Service)
Note  Sessions created in NO_ACKNOWLEDGE receipt mode cannot be used to create durable subscribers.
Note  Also, queue receivers on a queue that is routed from another server are not permitted to specify NO_ACKNOWLEDGE mode.
EXPLICIT_CLIENT_ACKNOWLEDGE (requires use of TIBCO Enterprise Message Service)
EXPLICIT_CLIENT_ACKNOWLEDGE is like CLIENT_ACKNOWLEDGE except it acknowledges only the individual message, rather than all messages received in the session.
One example of when EXPLICIT_CLIENT_ACKNOWLEDGE would be used is when receiving messages and putting the information in a database. If the database insert operation is slow, you may want to use multiple application threads all doing simultaneous inserts. As each thread finishes its insert, it can use EXPLICIT_CLIENT_ACKNOWLEDGE to acknowledge only the message that it is currently working on.
EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE (requires use of TIBCO EMS)
EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE mode is like TIBEMS-DUPS-OK-ACKNOWLEDGE except it "lazily" acknowledges only the individual message, rather than all messages received so far on the session.
Refer to the TIBCO Enterprise Message Service User’s Guide for more details on the JMS message delivery and acknowledgement modes.
When Enable Facade/Target JMS Transport is checked, four additional component configuration pages are added to enable settings for SOAP/JMS and ESD for both Facade and Target transport messaging where it may be applicable for your implementation. Click Next to enable and configure those settings.
Task E SOAP/JMS and ESB for Façade and Target Transport Messaging
Whether you are configuring the TIBCO API Exchange Gateway Component to instantiate the Configuration GUI, Core Engine, Core Engine with the Cache Agent Enabled, Global Throttle Manager, Cache Agent, Cleanup Agent, or the Central Logger... the following Four Component Wizard configuration pages are present in all Component Wizards to enable and configure transport messaging settings between the various component servers for both the Facade and Target. The following pages all have the same parameters and serve to connect TIBCO API Service Gateway Configuration UI with the appropriate messaging transport.
Figure 7 Similarities between SOAP/JMS and ESB, façade and target settings pages
To avoid repetition of the same parameter descriptions for each page and for each TIBCO API Exchange Gateway Configuration UI or Engine type, parameters will be explained once, for all applicable Component configurations.
Enable Transport - You may enable one or many of the transport settings for either the Façade (client request) or Target (data services/sources) using either SOAP/JMS and/or ESB transports. Configuration settings may be modified if you enable a transport for the component.
Request Queue - Specifies the queue name for the requests channel communication. An exact match request queue must exist on the JMS provider at the facade/target side when the component is started.
Reply Queue - Specifies the queue name for the reply (response) channel communication. An exact match reply (response) queue must exist on the JMS provider at the facade/target side when the component is started.
JNDI Context Factory - The default value for the initial Java Naming and Directory Interface (JNDI) context factory points to TIBCO Enterprise Message Service. If you’re using another JMS provider you can change the JNDI context factory here.
Topic Connection Factory Name - Specifies the name of TopicConnectionFactory object stored in JNDI. This object is used to create a topic connection on either the facade or target side depending on which configuration page it is being specified.
Queue Connection Factory Name - Specifies the name of QueueConnectionFactory object stored in JNDI. This object is used to create a queue connection with ESB services at either the facade or target side depending on which configuration page it is being specified. The Queue Connection Factory Name specified has to match the Queue Connection Factory Name defined for use in the JMS provider. When using a third-party JMS provider the Queue Connection Factory Name must match in this field and in the JMS provider.
Use Exported JMS Connection Settings from EMS Component - If you are using TIBCO Enterprise Message Service you can check this box and skip configuration of the parameters described below. Checking this box will add a Component Wizard page (shown below) to allow you upload the appropriate JAR files (jms-2.0.jar and tibjms.jar for TIBCO EMS) to set and establish connections.
Figure 8 Upload JAR files
Note: A relative path can be specified, but it is not necessary.
JMS Provider URL - Specifies the connection URL for either the JMS provider or TIBCO EMS used for either the facade or target operation requests.
JNDI Context URL - Specifies the URL to the JNDI service provider used for facade or target operation requests within the communication domain.
JMS Username - Specifies the user name for logging into the JMS provider or TIBCO EMS in the domain at either the facade or the target side.
JMS Password - Specifies the password for logging into the JMS provider
JNDI Username - Specifies the user name for logging into the JNDI server in the domain at either the facade or the target side. If the JNDI provider does not require access control, this field can be empty.
JNDI Password - Specifies the password for logging into the JNDI server communication domain at the facade or target side. If the JNDI provider does not require access control, this field can be empty.
Refer to the TIBCO Enterprise Message Service User’s Guide and the TIBCO API Exchange Gateway User’s Guide for more details.
Task F Log Reporting Messaging
When the Enable Reporting checkbox is selected, this page will appear to enable configuration of the log reporting.
Log Reporting Messaging Transport Type: Rendezvous or JMS. If TIBCO Rendezvous is used no further settings are necessary. If your implementation requires use of JMS for reporting, then consider proper values for the parameters.
Figure 9 Log Reporting Messaging
JMS Transaction Report Destination Name - Specifies the name of the JMS destination to which the transaction reports are sent to the Central Logger by the Core Engine.
JMS Transaction Report Destination Type - Queue or Topic. Specifies the type of the JMS destination to which the transaction reports are sent to the Central Logger by the Core Engine. The default value is queue.
The Central Logger always listens on a queue. If the value of destination type is changed to Topic, then the JMS administrator must configure a bridge between the topic and the queue.
Use Exported JMS Connection Settings from EMS Component- If you are using TIBCO Enterprise Message Service you can check this box and skip configuration of JMS Provider URL, JNDI Context URL, JMS Username, JMS password, JNDI Username, and JNDI password.
Checking this box makes a Component Wizard page display to allow you upload the appropriate JAR files (jms-2.0.jar and tibjms.jar) to set and establish connection settings.
Otherwise use the default values or other appropriate values for the parameters that become available when this checkbox is cleared.
Refer to the descriptions of these parameters in SOAP/JMS and ESB for Façade and Target Transport Messaging
Task G Configure the Parameters Used to Launch asg-engine
When the Enabler is set to launch a TIBCO® API Exchange Gateway Engine, Agent, or processing unit you will want to specify the parameters and properties for launching the API Service Gateway Engine (asg-engine).
Refer to the TIBCO® API Exchange Gateway User’s Guide for information on the command line parameters, options, and properties files used to run the TIBCO® API Exchange Gateway Core Engine.
Figure 10 TIBCO API Exchange Gateway: Parameters Used to Launch asg-engine
This Enabler Component Wizard is used to automate execution of the command line options for the installation of the asg-engine, the TIBCO® API Exchange Gateway Core Engine.
Using the various command line options presented in the Component Wizard you can programmatically launch and run a specific TIBCO® API Exchange Gateway processing unit or an agent as is described in the Processing Units of TIBCO API Exchange Gateway Engine section of the TIBCO® API Exchange Gateway User’s Guide.
Upload EAR file (optional) - Upload a TIBCO® API Exchange Gateway enterprise archive (EAR) to publish and run when the Component is instantiated at runtime.
Launch action: -u parameter - allows selection, configuration, installation, and launch from the following list of options:
Figure 11 Launch action: -u parameter options
 
Task H TIBCO API Exchange Gateway - Core Engine Settings
Set up reporting and messaging for the TIBCO API Exchange Gateway Core Engine. Enable reporting, facade and target JMS transport messaging, JMS delivery mode and JMS acknowledgement mode.
Figure 12 Set up the core engine for API Exchange component
Refer to TIBCO API Exchange Gateway Configuration UI and Core Engine Settings for descriptions on these settings.
If Facade/Target JMS Transport is enabled then proceed to SOAP/JMS and ESB for Façade and Target Transport Messaging.
When Reporting is enabled refer to Log Reporting Messaging for a description of how to set those identical settings parameters.
Task I Configure TIBCO® API Exchange Gateway Running Conditions
When the Enabler launches and runs the Gateway UI Configuration or an Engine, TIBCO Silver Fabric verifies that the product is running with a periodic check. if this component has specified the option to "install and configure without running to allow manual test of engine parameters" then this setting will not apply.
Polling Period (in seconds) for TIBCO® API Exchange Gateway verification (required) - This setting specifies the interval of time (in seconds) between verifications that TIBCO® API Exchange Gateway is still running. If TIBCO® API Exchange Gateway becomes unresponsive to this verification then the process is automatically restarted.
Figure 13 TIBCO® API Exchange Gateway Running Condition
Automatically Restart Silver Fabric Engine if TIBCO® API Exchange Gateway fails to restart N successive times (required) - Enter an integer to specify the number of restart retries for the TIBCO® API Exchange Gateway before the TIBCO Silver Fabric Engine will be restarted. A successful restart will reset the count.
Task J Central Logger Database Configuration
When the Component is being configured to launch the TIBCO API Exchange Gateway Central Logger with Database, the Database JDBC Connection configurations must be specified for use by the Central Logger.
Figure 14 Central Logger - Database Configuration
JDBC URL - Provides the protocol, database type, host and port to locate your database for the Central Logger
Username and Password - Make sure that a matching profile exists on the database. Required privileges are listed in the TIBCO API Exchange Gateway User’s Guide in the section, Database Setup and Configuration for Central Logger.
JDBC Driver Class - Sets the class path for the driver.
Upload JDBC Jar - Upload the third-party JDBC driver for your database so the component can be publish it with the Distribution.
Task K Add or Edit Enabler-specific Runtime Context Variables (optional)
String, Environment, System, or Encrypted variables may be added to the Component to define and set runtime specific context variables. Review the settings that were made previously and if required you can add or edit variables as necessary.
Select a variable type from the Add Variable pull-down list or Add from Enabler.
To change a variable value select the row and click Edit to change its value. Selected rows may also be removed.
Figure 15 Selecting a Variable prior to edit
 
Variable values from an Enabler may be added to the runtime as well. Use the Add from Enabler button to add Enabler-specific context variables.
Task L Add Allocation Rule Settings
Add rules to specify and set Component behavior. Add rules to do the following:
Each rule selection will bring up a slightly different dialog window that allows property selection of a tracked Engine or Component Archive statistic to be evaluated according to a logical operator and a value you specify to define an action. In some cases the Component Archive Statistics may be selected as is shown in the example below.
Figure 16 Setting a Threshold Activation
More information on using statistics for micro-scaling or archive scaling is available in the TIBCO Silver® Fabric Cloud Administration Guide and more about Component Archive scaling within a Stack is covered in this guide.
 
Task M Finish Configuring the Component
The remaining screens of the Component Wizard are generic for all Silver® Fabric Enablers. The configuration of these is optional for the TIBCO® API Exchange Gateway component.
Refer to TIBCO Silver® Fabric User’s Guide for more information on these configuration screens.
After you click the Finish button, make sure that the Component is published to make it available when creating a Stack.
To do this, select Publish Component in the Actions drop-down list located at the line of the Component you just created.
 

Copyright © 2014 TIBCO Software Inc. All Rights Reserved