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


Chapter 2 Creating an Enabler for Generic Adapter Component : Updating the Stack

Updating the Stack
When a stack is published and running, you can still make changes to the stack such as adding other components, changing allocation rules, changing threshold activation rules, or deploying and starting archives on the runtime Adapter Application instantiated on the engine.
Making changes to the stack is as easy as editing, saving, and publishing those changes to any instances that are running. Some changes might require restart of the changed resource, so consult the TIBCO Silver Fabric documentation for best practices prior to making changes to a production system.
After making any changes to a stack, save the changes and then from the Actions list in the main stack page, select Publish Changes. The specified engines are affected by the changes immediately.
If you want to change an Adapter component, you do not need to stop and restart your entire stack. If you want to deploy, start, stop, and undeploy the project archives, follow these methods:
Micro-scaling - Start and stop Adapter archives based on your defined rules when they are already in your component.
Continuous Deployment (deploy archives directly to endpoints) - publish (deploy), unpublish (undeploy), start, or stop archives without having to change any stacks, components, or engines. Deploying application archives through REST and cURL commands is described in the next section.
Deploying Archives Directly to Endpoints - Continuous Deployment
Deploying archives directly to a running TIBCO Generic Adapter component can be useful, such as when an archive must be deployed and run on a system that is already running. This is known as continuous deployment. Archives can be directly deployed to Adapter instances already running on Silver Fabric Engines using the command-line interface (CLI), Silver Fabric API, Ant scripts, or an HTTP REST command sent using cURL or a Java client. Refer to the TIBCO Silver Fabric Cloud Administration Guide for more information on the CLI or the Silver Fabric API. Archive deployment, undeployment, starting, and stopping application archives through REST are described in further detail here. For details on Ant scripts, refer to the chapter “Silver Fabric Ant Tasks” in TIBCO Silver Fabric Developers Guide.
TIBCO Silver Fabric supports many HTTP REST commands to GET, PUT, POST, and DELETE objects and managed resources for use with archive scaling, brokers, components, daemons, enablers, gridlibs, schedules, stacks, and Skyway.
TIBCO Silver Fabric REST Services are documented in the TIBCO Silver Fabric Administration Tool at Admin > REST Services. They are grouped by resource. Click any method name to see possible parameters if any and example responses.
Continuous deployment is discussed in good detail in the section on Deploying Archives Directly to Components in the TIBCO Silver Fabric Administration Guide.
Prior to using REST CLI with TIBCO Silver Fabric 5.6, you must change the setting, Strict Validation, at Config > Broker > General to "false".
The TIBCO Silver Fabric Enabler for Generic Adapter adds more REST methods to enable control of Adapter archives.
Continuous Deployment Life Cycle
The continuous deployment life cycle has four REST operations that can be executed using cURL methods:
Deploy Send an archive to a Silver Fabric Engine running a Generic Adapter component that meets the criteria specified. The Deploy REST method enables specification of a properties files with criteria dictating where and how the archive should be deployed.
Start Start an archive that was deployed to an engine.
Stop Stop an archive that is running on an engine.
Undeploy Remove an archive from an engine, stopping any running instances of that archive on that engine.
Deploy
The Adapter application archives may be deployed directly to an appropriate Silver Fabric Engine (TIBCO Logical Machine) by making REST calls. In this document cURL syntax is used to show the REST inputs in a generic form:
curl -u UserName:Password \
     -X POST \
     -H "Accept:application/json" \
     -H "Content-Type: multipart/form-data" \
     -F "archiveFile=@YourArchiveName.zip" \
     -F "deploymentFile=@YourDeploymentFileName.properties" \
    [-F "LogicalAnd=false"]
     -v "http://YourSFBroker.com:<port>/livecluster/rest/v1/sf/engines/archives"
    [-F "AppName=YourDirABC/YourAppName"]
    [-F "AppSettings.element1.element2=SomeValue"]
    [-F "ArchiveSettings.element1.element2=SomeValue"]
    [-F "Archives=Archive_A,Archive_B,Archive_X"]
    [-F "configurationFile=YourConfigurationfile.xml"]
    [-F "ForceDeploy=true"]
    [-F "GV=globalVariableA=123,globalVarB=SomeString"]
    [-F "InstanceSettings.element1.element2=SomeValue"]
    [-F "NoDeploy=true"]
    [-F "NoStart=true"]
    [-F "VariableProvider=Some_PROVIDER(S)_Name"]
Expressions in the generic form cURL expression as mentioned earlier were separated by line breaks to help with readability, but normally a string is submitted in the execution as in the following example.
Example 1 An example cURL archives deploy statement:
curl -u admin:admin -X POST -H "Accept:application/json" -H "Content-Type: multipart/form-data" -v http://MySFBroker.com:8080/livecluster/rest/v1/sf/engines/archives -F "archiveFile=@MyProcessOrder.ear" -F "AppName=MyOrders/MyProcOrder" -F "deploymentFile=@MyDeployCriteria.properties"
Where the user specified by -u must have Silver Fabric administrator level permissions, and the form-data fields (-F "property=value") may be specified in any order. The form-data fields (-F) are described as follows:
Mandatory form-data contain the files necessary for the deployment:
archiveFile: specifies the archive file (.zip, .par, or .ear file) to upload to the Silver Fabric Broker, which then publishes the archive to the appropriate Silver Fabric engine. Multiple application archives may be deployed in a single archive .zip or .ear file. You can deploy and run them all (default behavior) or you can selectively run a list of archives by specifying that list with the Archives form-data field. Archives may also be uploaded using the component wizard.
deploymentFile: specifies the properties file that defines the endpoint selection criteria described as follows in more detail.
     -F "deploymentFile=@YourDeploymentFileName.properties"
LogicalAnd (optional): by default all criteria specified in the deployment properties file must be satisfied for deployment to an application endpoint, but that can be toggled to mean any (meaning logical OR) of the deployment properties criteria by setting:  -F "LogicalAnd=false"
-v: specifies the target of the cURL POST execution and asks for a verbose response. The cURL -v expression should specify the appropriate Silver Fabric directory. For the default installation, that expression would look like the following:
 -v "http://YourSilverFabricBrokerName.com:<port>/livecluster/rest/v1/sf/engines/archives"
Where the default http <port> is 8080 and optional form-data fields can specify other continuous deployment behavior.
AppName: specifies the directory location where the application archives are deployed and what the application is named.
Where your archive application deploys and what it is called depends on what you specify with AppName. For example, when you use TIBCO Designer to create an .ear file with a name such as MyAppArchive, varying the AppName specification gives following behavior:
If the AppName form-data field is not specified, MyAppArchive is deployed at the top level of the directory.
If -F "AppName=A" is submitted in the curl request, MyAppArchive is renamed A and deployed at the top level.
If -F "AppName=A/" is sent, the directory folder A is used or it is created and MyAppArchive is deployed within that subdirectory.
If -F "AppName=A/B" is sent, the subdirectory A is used or created, and MyAppArchive is deployed there and renamed B.
If -F "AppName=A/B/" is sent, the folder A with a subfolder B is used or created and MyAppArchive is published within the subfolder B.
The full application name is derived from the AppName directory location and the application archive name as it is deployed.
Optional form-data fields do not need to be specified unless you want to change the default behavior. By default, all archives in the archive file are deployed and started. But if an archive of the same name is already deployed and started, then that archive is allowed to run without interruption or replacement.
AppSettings (optional): specifies settings that your application uses when deployed.
All deployment configuration cURL expressions takes the form:
 -F "AppSettings.element1.element2=SomeValue"
Some examples:
 -F "AppSettings.localRepoInstance.encoding=UTF-8"
 -F "AppSettings.description=This%20application%20deployment%20is%20for%20validation%20testing."
Where the element is one of the following (plus any subordinate element2 where applicable):
description: a string describing the application
contact: a string to name the person responsible for the deployment.
maxDeploymentRevision: specifies the default number of application revisions to keep in the revision history for each deployed application. Leave the value at -1 to keep all revisions by default.
localRepoInstance: for Enabler installed components and application archives installed with continuous deployment, a local file (or directory of files) is used as the deployment repository instance.
a.
encoding: specifies encoding for the repository instance. If this element is not specified, the encoding for the admin server is used. If the admin server is not available, the default for this element is ISO8859-1.
Archives (optional): form-data parameter that specifies a comma delimited list of archives that are to be deployed within the .zip file that are to be deployed. If an archives list is omitted, all archives in the application archive package are deployed. Example:
 -F "Archives=Archive_A,Archive_B,Archive_X"
ArchiveSettings (optional): form-data parameter specifies settings for the archive. Types of ArchiveSettings are as follows:
enabled: true or false. Only enabled services are deployed. Disabling a service effectively undeploys just that service while letting all other services in the application run as normal. This can be useful when you wish to deploy an application that includes a service, for which you do not have the required software. A deployment configuration cURL expressions takes the form:
 -F "ArchiveSettings.enabled=true"
av: specify values for archive runtime variables with a comma-separated string with each key value pair joined by an equal (=) sign. For example:
-F "ArchiveSettings.av=Deployment=T2.HTTP_GET-Tomcat,Domain=Mine"
Refer to the appendix of the TIBCO Runtime Agent Scripting Deployment User’s Guide for a full list of Archive Settings properties, parameters, descriptions, and usage. Not all elements and properties are supported for use by the TIBCO Silver Fabric Enabler for Generic Adapter . The following is the first attempt at listing them all.
ruleBases: rule bases for the archive
ruleBase.uri: location of the rulebase file. Example syntax:
 -F "ArchiveSettings.ruleBases.ruleBase.uri=someValue"
ruleBase.data: Rulebase content. Do not change this setting.
failureType: ANY, FIRST, SECOND, Subsequent
If an event is used, type must be specified.
Example syntax:
-F "ArchiveSettings.failureEvents.failureEvent.failureType=ANY"
restart: true or false. If true, the service instance is restarted upon failure.
description: information that describes this operation.
alertAction.performPolicy: the policy to perform. Once:generates an alert only for the first occurrence. Always:generates an alert for each occurrence.
alertAction.enabled: true or false. If true, the action occurs when conditions for the action are true. If false, the action is not called.
alertAction.level: High, Medium, Low
alertAction.message: The message that displays when this alert is triggered.
performPolicy: the policy to perform.
Once:generates an alert only for the first occurrence.
Always: generates an alert for each occurrence.
enabled: true or false. If true, the action occurs when conditions for the action are true. If false, the action is not called.
message: the message to send
to: a comma-separated list of email addresses to which the messages are sent
cc: a comma-separated list of email addresses to which copies of the messages are sent
subject: the subject of the email message
sMTPServer: The mail server (SMTP server) to use to send the message. Specify the host name or the host IP address
performPolicy: the policy to perform.
Once: generates an alert only for the first occurrence.
Always: generates an alert for each occurrence.
enabled: true or false. If true, the action occurs when conditions for the action are true. If false, the action is not called.
command: specify the script to execute. A good practice is to use script files.
arguments: the list of arguments for the command
restart: true or false. If true, the service instance is restarted upon failure.
description: information that describes this operation.
alertAction.performPolicy: the policy to perform. Once: generates an alert only for the first occurrence. Always: generates an alert for each occurrence.
alertAction.enabled: true or false. If true, the action occurs when conditions for the action are true. If false, the action is not called.
alertAction.level: High, Medium, Low
alertAction.message: the message that displays when this alert is triggered.
emailAction.performPolicy: the policy to perform. Once:generates an alert only for the first occurrence. Always: generates an alert for each occurrence.
emailAction.enabled: true or false. If true, the action occurs when conditions for the action are true. If false, the action is not called.
emailAction.message: the message to send.
emailAction.to: a comma-separated list of email addresses, to which the messages are sent.
emailAction.cc: a comma-separated list of email addresses, to which copies of the messages are sent.
emailAction.subject: the subject of the email message.
emailAction.sMTPServer: the mail server (SMTP server) to use to send the message. Specify the host name or the host IP address.
customAction.performPolicy: the policy to perform. Once: generates an alert only for the first occurrence. Always:generates an alert for each occurrence.
customAction.enabled: true or false. If true, the action occurs when conditions for the action are true. If false, the action is not called.
customAction.command: specify the script to execute. A good practice is to use script files.
customAction.arguments: the list of arguments for the command
restart: true or false. If true, the service instance is restarted upon failure.
Example syntax:
 -F "ArchiveSettings.logEvents.logEvent.restart=true"
match: the string in the log file to match
description: information that describes this operation
alertAction.performPolicy: the policy to perform. Once:generates an alert only for the first occurrence. Always:generates an alert for each occurrence.
alertAction.enabled: true or false. If true, the action occurs when conditions for the action are true. If false, the action is not called.
alertAction.level: High, Medium, Low
alertAction.message: the message that displays when this alert is triggered
emailAction.performPolicy: the policy to perform. Once: generates an alert only for the first occurrence. Always:generates an alert for each occurrence.
emailAction.enabled: true or false. If true, the action occurs when conditions for the action are true. If false, the action is not called.
emailAction.message: the message to send.
emailAction.to: a comma-separated list of email addresses, to which the messages are sent.
emailAction.cc: a comma-separated list of email addresses, to which copies of the messages are sent.
emailAction.subject: the subject of the email message
emailAction.sMTPServer: The mail server (SMTP server) to use to send the message. Specify the host name or the host IP address.
customAction.performPolicy: the policy to perform. Once: generates an alert only for the first occurrence. Always: generates an alert for each occurrence.
customAction.enabled: true or false. If true, the action occurs when conditions for the action are true. If false, the action is not called.
customAction.command: specify the script to execute. A good practice is to use script files.
customAction.arguments: the list of arguments for the command
failureCount: the value in this field defines how many restarts should be attempted before resetting the error counter to 0.
failureInterval: the value in this field defines how much time should expire before resetting the error counter to 0.
InstanceSettings - (optional) Some syntax examples:
-F "InstanceSettings.initHeapSize=64"
-F "InstanceSettings.maxHeapSize=512"
-F "InstanceSettings.threadStackSize=512"
description: specify any pertinent information about the binding.
contact: contact responsible for this application instance.
startOnBoot: when true, the service instance starts when the computer is restarted. The default value is false.
prepandClassPath: the values supplied here are prepended to your CLASSPATH environment variable.
appendClassPath: the items you supply here are appended to your CLASSPATH environment variable.
initHeapSize: specifies the initial size (in MB) for the JVM used for the process engine. The default is 32 MB.
maxHeapSize: specifies the maximum size (in MB) for the JVM used for the process engine. The default is 256 MB.
threadStackSize: specifies the size of the thread stack. The default is 256 KB.
runAsNT: when set to true the service is run as a Microsoft Windows Service. You can then manage the engine as you would any other service, and you can specify that it starts automatically when the machine reboots.
startUpType: specifies the instance service startup type as either: Automatic, Manual, or Disabled.
login: specifies the login account for the service, if any. The domain name must be specified as well.
password: sets the password for that service, if any.
checkpoint: when set to true, the process engine waits for all jobs to finish (up to the maximum timeout) before shutting down the engine, rather than remove jobs at their next checkpoint.
iv : this element uses a comma-separated string with name-value pairs with each key value pair joined by an equal (=) sign. For example:
configurationFile (optional): form-data parameter used to include an XML configuration file created to modify archive properties if needed. Example syntax:
 -F "configurationFile=YourConfigurationfile.xml"
Where your XML configuration file should use the same format as an enabler or component level configure.xml file with the outermost XML element as follows:
 <archiveConfig name="YourArchiveName">
    ...
 </archiveConfig>
 
For more information on writing an archive configuration file, see the "Using the Silver Fabric SDK" chapter of Silver Fabric Developer’s Guide.
 
ForceDeploy (optional): redeploy, forces a stop and overwrite of a pre-existing archive or set of archives with the same name. By default ForceDeploy is set to false and so a second deployment does not overwrite a pre-existing deployment of the same name. If a change of the archive file, ForceDeploy should be set to true so that the new application archive is redeployed. If ForceDeploy is used with -F Archives specifying a comma delimited list, only those archives are stopped, undeployed, and redeployed.
 -F "ForceDeploy=true"
 
VariableProvider (optional): specifies a variable provider to set global variables for applications deployed with REST. The variable provider is a Java Class extension compiled into a JAR and loaded into a Silver Fabric directory with an appropriate XML so that it may be called by REST during application deployment. It supports multiple VariableProviders at the same time. You can add multiple variable provider names with a comma separated list. If you use the global variable name in both variable providers, the latest in the list is used.
 -F "VariableProvider=Some_PROVIDER_Name"
Creating a Variable Provider for Use by a REST call
1.
Create a class that extends com.datasynapse.fabric.broker.userartifact.variable.AbstractVariableProvider and override the methods as needed. For example:
package com.tibco.sf.providers;
import java.util.Properties;
import com.datasynapse.fabric.broker.userartifact.variable.AbstractVariableProvider;
public class My_Var_Provider extends AbstractVariableProvider
{
private static final long serialVersionUID = 1L;
@Override
public Properties getVariables()
{
Properties p = new Properties();
p.setProperty("MyApp/vars/name", "SomeString");
p.setProperty("MyApp/vars/episodic", "true");
p.setProperty("MyApp/vars/Xduration", "60");
return p;
}
@Override
public void destroy()
{}
@Override
public void init() throws Exception
{}
}
2.
SILVERFABRIC_HOME/webapps/livecluster/deploy/config/variableProviders
3.
<variableProvider class="com.tibco.sf.providers.My_Var_Provider">
   <property name="name" value="Some_PROVIDER_Name"/>
   <property name="description" value="GV values are in the JAR"/>
   <property name="enabled" value="true"/>
</variableProvider>
The variable provider name used by the REST statement is specified as "name" in the XML file.
Save the XML file in the same directory as the JAR: 
SILVERFABRIC_HOME/webapps/livecluster/deploy/config/variableProviders
You can verify what variable providers are ready for use by REST invocation on the TIBCO Silver Fabric Administrator > Admin > Variables page.
NoStart - (optional) default value is false, meaning that the archives are both deployed and started by default. If NoStart is set to true, the application is deployed but not started.
 -F "NoStart=true"
Deployment File
When deploying an archive by REST you must include a deployment file, which specifies at least one selection criteria for determining which engine and component receives the deployed archive. The deployment file is a simple properties text file specified by a form-data field like the following for REST upload with the archive:
     -F "deploymentFile=@YourDeploymentFileName.properties"
The deployment file contains one or more logical statements with a criteria, a comparator, and a value, delimited by spaces:
criteria comparator value
Some criteria require an argument to be specified in parentheses:
criteria(argument) comparator value
For example, what follows is a simple statement to deploy an archive to an engine running a component with a component type that contains Adapter as part of the name and which has a domain name of YourDomain:
ComponentType contains Adapter
ImportedVariable(TIBCO_DOMAIN_NAME) = YourDomain
By default all deployment file criteria statements must be satisfied for the deployment to occur, but you can change how the properties file criteria are evaluated to make them logical OR statements by using the optional cURL form-data switch:   -F "LogicalAnd=false"
 
Table 3 Supported Criteria
DependencyEngine(componentName)
Comparator Valid comparators include =, !=, >, <, <=, >=, matches, contains, !matches, and !contains.
Example 2 A sample deployment file
# Sample deployment file
ComponentType = "TIBCO Generic Adapter"
 
ActivationInfoProperty(ClusterName) matches dev_cluster.*
Successful Deployment
REST returns a Status of 200 (OK) when the archive is successfully deployed. A successful REST execution returns the Engine-Instance and Engine-Id where the archive deployed. Example response (application/JSON):
{
"result": {
"name": "Archive Deployment",
"value": {
"message": "ENGINE '[1885509966828815621-5 : my_archive.ear]' DEPLOYED",
"Engine-Instance": "5",
"Engine-Id": "1885509966828815621"
}
},
"status": 200
}
Knowing the Engine-Id, Engine-Instance, and the full ArchiveName allows for invocation of START, STOP, and UNDEPLOY methods to enable full control of the Archive life cycle.
An unsuccessful deployment returns an error of Status 500 or some other appropriate error status depending on the cause.
Continuous Deployment Timeout
Continuous deployment transfers can timeout due to one or more of the following factors:
If you are encountering timeout issues, you can set a higher socket timeout between the broker and engines. This can be set in the Silver Fabric Administration Tool at Config > Broker > Communications under the section HTTP Connections > Engines. The Socket Timeout parameter configures the HTTP connections established from brokers to clients and engines. Set the timeout value to the longest of the following three:
Start
Using REST you can also start application archives that are deployed but not started. You must know the Engine-Id, Engine-Instance, and the full application ArchiveName.
Example 3 Here is a generic cURL example that starts an Archive.
curl -u UserName:Password \
     -X POST \
     -H "Accept:application/json" \
     -H "Content-type: multipart/form-data" \
     -v "http://<YourSFBroker.com>:<port>/livecluster/rest/v1/sf/e
ngines/{engine-id}/{engine-instance}/archives/{appname}/start"
Expressions in this generic form cURL expression example were separated by line breaks to help with readability, but normally an unbroken string is submitted when executed.
The value of {engine-instance} can be obtained from the response to the successful cURL deployment REST execution or the TIBCO Silver Fabric Administrator > Engines page > expanding the row to see Engine details.
The Start and Stop both have an optional option to specify the version number.
If the version number is not specified, an attempt to complete the action is made on the deployed application with the same name.
Silver Fabric REST methods to GET the engine-id and engine-instance for all instances running on a daemon. Refer to "TIBCO Silver Fabric REST Services" documented in the TIBCO Silver Fabric Administration Tool at Admin > REST Services.
Example 4 Another cURL example that starts an archive
curl -u admin:admin
     -X POST
     -H "Accept:application/json"
     -H "Content-Type:multipart/form-data" http://lin64vm205.qa.datasynapse.com:8080/livecluster/rest/v1/sf/engines/5103224222683646426/3/archives/Adapter_PUB/start
     
The value of {appname} is usually the application name or the full application archive name.
When the {appname} is used, it is URL-encoded in a cURL statement so that spaces are converted to "%20" and forward slashes (/) are represented by "%2F". Likewise, other special characters must be encoded appropriately.
Stop
You can stop application archives that are running on an engine by REST method by submitting a cURL expression to the Silver Fabric Broker. You must know the Engine-Id, Engine-Instance, and the full application ArchiveName.
curl -u UserName:Password
     -X POST
     -H "Accept:application/json"
     -H "Content-type: multipart/form-data" \
     -v "http://<YourSFBroker.com>:<port>/livecluster/rest/v1/sf/e
ngines/{engine-id}/{engine-instance}/archives/{appname}/{archive-id}/stop"
 
Example 6 A cURL example that stops an Archive:
curl -u admin:admin
     -X POST -H "Accept:application/json"
     -H "Content-Type:multipart/form-data" http://lin64vm205.qa.datasynapse.com:8080/livecluster/rest/v1/sf/engines/5103224222683646426/3/archives/Adapter_PUB/stop
Refer to the Start method for a description on how to obtain the values of {engine-id}, {engine-instance}, and {appname}.
Undeploy
You can undeploy application archives that are running on an engine by REST method by submitting a cURL expression to the Silver Fabric Broker. You must know the Engine-Id, Engine-Instance, and the full application ArchiveName.
curl -u UserName:Password
     -X POST
     -H "Accept:application/json"
     -H "Content-type: multipart/form-data" \
     -v "http://<YourSFBroker.com>:<port>/livecluster/rest/v1/sf/engines/{engine-id}/{engine-instance}/archives/{appname}/undeploy"
 
Refer to the Start method for a description on how to obtain the values of {engine-id}, {engine-instance}, and {appname}.
DeleteApp - (optional - use with undeploy only) The default value is false and it can be omitted. When the DeleteApp parameter is false, an undeploy archive action leaves the application configurations of global variables and bindings so that they can be used again. The archive and the application are only undeployed and not deleted.
Setting DeleteApp to true deletes the application and the associated variable settings from the runtime engine after the archive is undeployed.
Example 7 A cURL example of an undeploy call
curl -u admin:admin
     -X POST
     -H "Accept:application/json"
     -H "Content-Type:multipart/form-data" 
     -v "http://lin64vm205.qa.da
tasynapse.com:8080/livecluster/rest/v1/sf/engines/5103224222683646
426/3/archives/Adapter_PUB/undeploy"
Here the application name is used and archiveid is not used.
The Archive Management Support Feature
When components are activated, by default all archives are deployed in order, and then started in order. This behavior can be changed by editing the component in the component wizard, and editing the Archive Management Support feature, which has an option that can be cleared to prevent archives from starting when the component is activated.

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