Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 2 Creating an Enabler for Generic Adapter Component : Creating Generic Adapter Components

Creating Generic Adapter Components
This component can perform the following tasks:
If you do not upload the Adapter projects, you still can publish the Adapter projects on the machine where Adapter is registered to the TIBCO domain using the TIBCO Administrator GUI.
Prerequisite
Before creating the TIBCO Generic Adapter component, you must first create a TIBCO Administrator component. It creates a TIBCO domain, and starts TIBCO Hawk® services and a TIBCO Administrator server. Refer to TIBCO Silver Fabric Enabler for TIBCO Administrator - Enterprise Edition User’s Guide for creating and configuring a TIBCO Administrator component.
To configure a Generic Adapter component, perform these tasks:
Task A Specify the Component Type and Name
1.
2.
In the Components page, select Create New TIBCO Generic Adapter Component from the Global Actions drop-down list.
Figure 1 Creating a New TIBCO Generic Adapter Component
3.
Enter a Distribution Name for your distribution.
4.
In Distribution Minimum, enter the minimum version of the distribution for the Silver Fabric to resolve all of the available distributions.
5.
In Distribution Maximum, enter the maximum version of the distribution for the Silver Fabric to resolve all of the available distributions.
6.
Check the Enable product registration option for the custom software to register itself as custom software on the TIBCO Administrator. It validates product registration.
Figure 2 Configure General Properties
Task B Select the Software Product Versions
You can select the versions of the distributions for TIBCO Generic Adapter to run, as shown in Figure 3.
1.
All distributions may not be compatible with your specific environment. All versions of the distributions are compatible with the Silver Fabric Enabler, but certain distributions may support only specific operating systems as deployment destinations.
Figure 3 Software Version
 
2.
Choose Optional Distribution(s) - If your TIBCO Administrator implementation makes use of TIBCO Enterprise Messaging Service, you must upload the latest TIBCO EMS distribution to the TIBCO Silver Fabric Broker.
Figure 4 Choose Optional Distributions
Task C Set the Basic Configuration
In the TIBCO Generic Adapter Basic Configuration page, you can upload a JDBC driver, set a specific TIBCO domain machine name (the TIBCO Logical Machine name - TLM), provide for specification of Fast TLM Restart, and allow uploading of external jar files and prepending/appending the path in the ClassPath. It also provides for the specification of either full or short archive names.
Each of the settings on this page is described in the order of its appearance on the page.
1.
Specify a JDBC driver to publish with the TIBCO® Generic Adapter Distribution for TIBCO Silver® Fabric so that it can communicate with the TIBCO Administrator domain database. When the TIBCO Administrator uses a database as the domain storage, you must upload a JDBC driver so the component can interact with it.
The JDBC driver must match the database type used by the TIBCO Administrator. This procedure is the same as uploading a JDBC driver for the TIBCO Administrator component.
If the domain is not stored in a database, do not upload a JDBC driver.
Figure 5 Upload a JDBC Driver for TIBCO Domain Storage
 
2.
The TIBCO Domain Logical Machine Name (also known as the TIBCO Logical Machine name - TLM) provides for publishing of a unique component.
TLM is the machine name you see in the TIBCO domain where Adapter is installed. The TIBCO domain Logical Machine virtualizes the machine publishing so that component publishing can maintain state when the targeted engine is changed for whatever reason.
If for example, the target machine is restarted because of an OS update or a hardware change, TLM allows for the virtualized machine to be restarted on different hardware.
TIBCO Domain Machine Name - To activate use of the TIBCO domain Logical Machine Name, enter a value that is unique in the TIBCO domain machine name field. The machine name is a virtual name and must be unique. You can use alphanumeric characters, hyphen (-), or underscore (_) characters. Other special characters, including period or comma, are not allowed. The name length must be less than 64 characters.
When the component is instantiated multiple times, the TLM machine name gets the name: <Your_TLM_Name>_<ComponentInstanceNumber> , where the <ComponentInstanceNumber> is just a sequential incrementing integer.
If <ComponentInstanceNumber>=0, the TLM machine name is <Your_TLM_Name>. when <ComponentInstanceNumber>>0, the TLM machine name is <Your_TLM_Name>_<ComponentInstanceNumber>.
Figure 6 Configure the TIBCO Logical Machine Name
3.
Fast TIBCO Logical Machine Restart provides for accelerated restart of the Engine and redeploying of many archives within a reduced amount of time. Enhanced restart times are achieved by using a saved state stored on a shared Network File System drive instead of synchronizing with the domain repository. It updates the deployment configuration file with the new binary location. To set your expectations properly, "fast" does not mean instantaneous, but it is faster than if the archives were loaded from the domain repository.
The shared NFS directory drive for Fast TLM Restart requires the following:
The shared drive must be READ/WRITE accessible to all engine daemons running as TIBCO Logical Machines in a TIBCO Silver Cloud. The degree to which you can guarantee reliability and availability of that shared drive helps to ensure runtime continuity.
If you want to force redeployment (synchronization with the domain) once, add a file call “ForceRedeploy.txt” in the domainDataHome (<domainDataDir>/<DomainName>/<TLMNAME>/<DomainName>. It redeploys all applications (no FAST TLM) at startup and then deletes the file (it is a one time action).
To enable Fast TIBCO Logical Machine Restart simply enter the directory path of the shared NFS drive (on Windows servers - a mapped drive) and make sure that the host grants permissions to the user launching the engines, to read and write in that location.
4.
Sets the desired services state when the TIBCO Logical Machine is restarted. When the TLM is restarted, the Adapter service instances is republished and appears as either started or stopped. The stopped services state setting may be convenient for developers who are testing machines with many services that do not need to be started for every logical machine change.
5.
Add external JAR file(s) to the Adapter Component - As an option, JAR files may be uploaded for publishing with the TIBCO Generic Adapter component.
The check box "Add the JAR file(s) in front of the Generic Adapter ClassPath (check), otherwise at the end of the ClassPath (unchecked)" means just what it says. The JAR file name may be prepended in front of the ClassPath by selecting the box and if it is left clear the JAR file name is appended at the end of the ClassPath.
 
Upload JAR file(s) in ZIP Format to Adapter ClassPath -
Upload individual JAR file(s) to be either appended or prepended to the ClassPath. All uploaded JARs are added in the same way according to how the check box is set.
To remove unwanted JAR files use the Menu button to display the list of Wizard configuration steps and select Add/Override/Customize Enabler and Component-specific content files. Relative paths to external jar files added may be removed from that window.
Task D Load External JAR Files
Upload and add JARs to the Generic Adapter Classpath with the JAR names as either a prefix or appended to the ClassPath.
The check box "Add the JAR file(s) in front of the Generic Adapter ClassPath (check), otherwise at the end of the ClassPath (unchecked)" means just what it says. The JAR file name may be prepended in front of the ClassPath by selecting the box and if it is left clear the JAR file name is appended at the end of the ClassPath.
Upload individual JAR file(s) to be either appended or prepended to the ClassPath. All uploaded JARs will be added in the same way according to how the check box is set.
To remove unwanted JAR files use the Menu button to display the list of Wizard configuration steps and select Add/Override/Customize Enabler and Component-specific content files. Relative paths to external jar files added may be removed from that window.
Task E Upload a Adapter Project
If you want TIBCO Silver Fabric Enabler for Generic Adapter to publish and run one or more Adapter projects, you must upload one or more EAR files (or compressed files). EAR and .zip files are briefly described in the note following Step 2: TIBCO Designer EAR and ZIP files. Enable the Generic Adapter project as follows:
1.
Click the Add button in the Upload, Remove, or Recorder Archive Files panel.
Figure 7 Uploading an EAR or ZIP Archive File
 
2.
Click the Browse button and navigate to the EAR, .zip, or J2EE WAR file.
To create an appropriate XML file, follow these steps:
To create a deployment configuration properties XML file for either an EAR deployment or for an archive continuous deployment, follow these steps:
a.
In TIBCO_HOME/tra/tra_version/bin, run the following command:
AppManage –export –ear EarFile.ear -out DeploymentConfig.xml
b.
c.
Create a .Zip file with the file EarFile.ear and DeploymentConfig.xml.
For details about the creation of the DeploymentConfig.xml file, refer to the TIBCO Runtime Agent documentation, Scripting Deployment User’s Guide..
A CustomFolder.properties file put in the zip archive can specify the deployment path. For example, create the CustomFolder.properties file with content "ApplicationFullPath=aaa/bbb/ccc".
Task F Hawk Application Management Interface (AMI) Configuration (optional)
TIBCO Hawk AMI may be used to monitor Generic Adapter for deployments.
Figure 8 TIBCO Hawk AMI Configuration
AMI Hawk Service: specifies the TIBCO Hawk port number, for example, TIBCO Rendezvous connects with TIBCO Hawk on the default port 7474. AMI Hawk Service and AMI Hawk Daemon must be set with valid values together. Setting only one of them results in an error.
AMI Hawk Daemon: specifies the location of the TIBCO Hawk Daemon. A value of "tcp:yyyy" corresponds to a local Hawk Daemon, where "yyyy" is the port number. A Hawk Daemon located elsewhere is specified by a value of the protocol, IP address, and port number: "tcp:xxx.xxx.xxx.xxx:yyyy".
The AMI Hawk Service and the AMI Hawk Daemon ports may be the same or they may be different. By default, different TLMs on the same engine daemon (physical machine) are using the same RV transport (default AMI Hawk Service=7475, and default AMI Hawk Daemon=tcp:7474). This setting enables visibility of all of the deployed applications on each TLM even if some applications are NOT deployed on this particular TLM.
Generally, AMI Hawk Network is an empty string.
Task G Configure TIBCO Hawk Agent Running Condition
Use the following options to configure running conditions for TIBCO Hawk agent:
Enter an integer to specify the number of seconds between periodic verification checks that the TIBCO Hawk Agent is still running.
If the TIBCO Hawk Agent becomes unresponsive to this verification, the process automatically restarts.
Figure 9 TIBCO Administrator and Hawk Agent Running Conditions
Enter an integer to specify the number of restart retries for the TIBCO Hawk Agent before the TIBCO Silver Fabric Engine is to be restarted. A successful restart resets the count.
Task H Uploading Hawk MicroAgent Plugin (optional)
You can upload Hawk MicroAgent plug-ins to HawkAgent as a .zip file. These Hawk microagents collect information and operate using that information. They execute specific tasks known as methods.
The zip file gets extracted into the HMA plugin directory. If the directory is not empty, select one of the following options:
Figure 10 Upload Hawk MicroAgent Plugin
Task I Register TLM Properties
The TIBCO Silver Fabric Enabler for Generic Adapter supports multiple SDK or TIBCO Adapters, and the TLM fast restart is specific and unique to each product.
You must provide the TLM properties that get affected while doing a TLM restart.
Figure 11 Adding TLM Properties
 
Figure 12 Setting TLM Properties
 
Task J Add/Edit Container Specific Runtime Context Variables
Add Runtime Context Variables:
String, Environment, System, or Encrypted variables may be added to the component to define and set runtime-specific context variables.
Select a variable type from the Add Variable pull-down list or Add from Enabler to use a variable from a selected Enabler.
Figure 13 Adding a Runtime Context Variable
After you have added any runtime context variable, select the variable (selected row is highlighted) and Edit to change its attributes. Selected rows may also be removed.
Changes are of course optional, because all variables have default values that are appropriate for the most common use cases.
Variable values from the Enabler may be added to the run time as well. Use the Add from Enabler button to add Enabler-specific context variables.
 
Edit Runtime Context Variables (optional)
Select a variable type from the Add Variable selector if you wish to edit a variable.
Figure 14 Editing a Variable
You can add a string variable to change pre-existing context variables such as: ARCHIVE_DETECTION_FREQUENCY.
Figure 15 Edit a String Variable
ARCHIVE_DETECTION_FREQUENCY is the periodic interval (the default value is 30 seconds) for detection of deployed archives and report to the broker. The broker uses this data to synchronize the archive with scaling rules.
These variables are not exposed in the interface elsewhere, but you can change their values. In this case, ensure that you set these variable values higher than the time needed to deploy and start an archive.
Changes are optional, because all variables have default values that are usually appropriate for the most common use cases.
Variable values from the Enabler may be changed as well. Use the Add from Enabler button to change values of Enabler-specific context variables.
Task K Add Enabler and/or Component-Specific Content Files
If needed, you can upload a content file (for example, the JDBC Jar file for mysql) specific to this component from this dialog. You can perform the following operations:
Upload: Upload new file.
Add from Enabler: Copy a content file from the Enabler to the component.
Customize: Modify the content file.
Remove: Delete the file.
You can add files to a relative path associated with the Adapter component that can be required for the component to run according to design.
Figure 16 Uploading Content Files
Task L Add or Remove Log File Patterns
You can edit or change the log pattern as needed. You can only add and configure the TRA based logs.
Click Add to add the log file pattern.
Click Add Default to add the default file pattern.
Figure 17 Adding or Removing Log File patterns
Figure 18 Adding a Log File pattern
Task M Add Allocation Rule Settings
Add rules to specify and set component behavior. Add rules to do the following actions:
Each rule selection brings up a slightly different dialog window. You can select property of a tracked Engine to be evaluated according to a logical operator and a value you specify to define an action.
Task N Generic Settings
The following tasks are generic for all Silver Fabric Enablers. The configuration is optional for the Generic Adapter components.
Almost all of the other screens are generic for TIBCO Silver® Fabric Enablers. Refer to TIBCO Silver® Fabric User’s Guide for more information on these configuration screens.
Click Finish to save your changes and then you can deploy the Application component as part of an Application stack.
To do this, select Deploy Application Component in the Actions list located at the line of the Application component you just created.
Use the Edit the Configuration File page with extreme caution. Do not use the page unless the configuration.xml file is backed up and specific knowledge about the TIBCO Silver Fabric system is being applied. This interface can be used for more advanced customizations and not otherwise.
For more information, refer to "The configure.xml File" section in TIBCO Silver® Fabric Developer’s Guide.
Figure 19 Edit the Configuration File Page
 
As an example, if a user wants to replace the property tibco.env.CUSTOM_PATH, tibco.env.CUSTOM_LIB_PATH and tibco.env.ODBCINI in ${TIBCO_HOME}/adapter/adadb/6.3/bin, the XML example code as described follows, accomplishes this when used in the Edit configuration file text field.
<?xml version='1.0' encoding='utf-8' standalone='yes' ?>
<containerConfig>
  <configFiles baseDir="${TIBCO_HOME}/adapter/adadb/6.3/bin"     include="adbagent.tra">
    <regex pattern="tibco\.env\.CUSTOM_PATH"       replacement="tibco.env.CUSTOM_PATH xxxx" />
  </configFiles>
  <configFiles baseDir="${TIBCO_HOME}/adapter/adadb/6.3/bin"     include="adbagent.tra">
    <regex pattern="tibco\.env\.CUSTOM_LIB_PATH.*"
      replacement="tibco.env.CUSTOM_LIB_PATH xxxx" />
  </configFiles>
  <configFiles baseDir="${TIBCO_HOME}/adapter/adadb/6.3/bin"     include="adbagent.tra">
    <regex pattern="tibco\.env\.ODBCINI.*"       replacement="tibco.env.ODBCINI xxxx" />
  </configFiles>
</containerConfig>
The property, baseDir, in the <configFiles> element specifies the path that includes the file to be updated. You can modify it if required. For example, if the TIBCO ActiveMatrix Adapter for Database (ADADB) version is 6.3 instead of 6.2, the baseDir value is:
${TIBCO_HOME}/adapter/adadb/6.3/bin
The property, include, in <configFiles> element specifies which files are to be replaced. It can specify the files you want to change. The asterisk wild card can be used to represent a string of characters, for instance: "*.tra" to change all of the .tra files in %baseDir%.
The property, pattern, in the <regex> element specifies the contents that are to be replaced within the previously specified files. The value of pattern can be a regular expression.
The property, replacement, in <regex> element specifies the new contents of the node specified by the pattern property value.
Where xxxx is the path in your implementation environment.
 
Task O Finish Configuring the Component
All the other screens are generic for all Silver Fabric enablers. The configuration is optional for Adapter components.
Refer to TIBCO Silver Fabric User’s Guide for additional information on these configurations.
After you click the Finish button, make sure that the component is published to make it available to create an application.
To do this, select Publish Component in the Actions drop-down list located at the left-hand side of the component you just created.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved