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


Chapter 2 Adapter Configuration : Accessing Configuration Information

Accessing Configuration Information
This section explains how the SDK encapsulates the information saved in the project repository, and how adapters access that information. It also includes a detailed description of the repository locator string.
Location of Configuration Information
The repourl and configurl specify the location of a project repository, which must be defined for a custom adapter.
repourl: the repository location, that is, the location of the project repository (repository instance).
Specify the repourl in one of the following ways:
Calling the MAppProperties method set to set the REPOURL before creating the MApp application manager.
appProperties.set(MAppProperties::REPOURL,"repoul")
Using the –system:repourl command line argument.
Setting tibco.repourl in a properties file.
configurl: the location of the adapter instance description object inside the project repository.
Specify the configurl in one of the following ways:
Calling the MAppProperties method set to set the configurl before creating the MApp application manager.
appProperties.set(MAppProperties::CONFIGURL, "configurl")
Using the –system:configurl command line argument.
Setting tibco.configurl in a properties file.
See Server-based Repository Locator String and Local Repository Locator String for instructions on how to specify the locator string.
Server-based Repository Locator String
Applications built with the TIBCO Adapter SDK use a repository resource locator string to specify the server-based repository location and parameters.
The parameters available depend on the protocol with which the client and server communicate.
TIBCO Rendezvous
In the case of a TIBCO Rendezvous transport, a URL begins with tibcr:// or tibcr@, followed by the instance name.
Table 14 lists the supported optional parameters. They are separated by colons.
TIBCO Rendezvous subject prefix used for regional read-operation in the load balancing mode. For more information see the TIBCO Administrator Server Configuration Guide.
CLIENT_USAGE_DONT_CARE—Client reads until update, then switches to write. This is the default.
CLIENT_USAGE_READ_ONLY—Client is not allowed to do updates.
CLIENT_USAGE_READ_WRITE—Client can do both reads and updates.
The legal properties in this file are the same as optional parameters specified above. The properties in the file are appended to the repository locator string. If the same property appears in both locator string and property file, the properties in the locator string take precedence.
Examples are given below:
tibcr://myInst:service=5456:userName=ann:timeout=4000
tibcr@myInst:service=5456:urlFile=/tibco/props/fredsProps.txt
tibcr://myInst:urlFile=/tibco/props/fredsProps.txt
HTTP and HTTPS
In the case of HTTP transports, a URL begins with http://. In the case of HTTPS transports, a URL begins with https://.
The host name and port number come next (http://host:port). The port number is optional. If not specified, the default value is 8080 for HTTP and 8443 for HTTPS. In the case of HTTP/HTTPS clients, the host name and port number are followed by a '?' (http://host:port) and the instance name.
HTTPS-specific properties should be placed in a property file and that file should be specified using urlFile=. Therefore, urlFile is a required parameter for HTTPS.
In addition, remote HTTP/HTTPS clients support the following optional parameters separated by &. When & is used as separator of parameters and the URL is specified on the command line, the URL should be enclosed in quotes so that shell does not interpret it.
CLIENT_USAGE_DONT_CARE—Client reads until update, then switches to write. This is the default.
CLIENT_USAGE_READ_ONLY—Client is not allowed to update.
CLIENT_USAGE_READ_WRITE—Client can both read and update.
The legal properties in this file are the same as optional parameters specified above. The properties in the file are appended to the repository locator string. If the same property appears in both locator string and property file, the properties in the locator string take precedence.
Property values starting with # are considered obfuscated.
Examples are given below:
http://host:8080/administrator/repo?myInst&userName=ann&timeout=4000
https://host:8443/administrator/repo?myInst&urlFile=httpsProps.ini
https://host:8443/administrator/repo?urlFile=httpsProps.ini
Local Repository Locator String
Local repositories start with the instance name, which can optionally be preceded by localrepo@. The instance name can either be a fully qualified path or a relative path. The .dat extension is optional. In addition, clients support the following optional parameters separated by colons.
The legal properties in this file are the same as optional parameters specified above. The properties in the file are appended to the repository locator string. If the same property appears in both locator string and property file, the properties in the locator string take precedence.
CLIENT_USAGE_DONT_CARE—Client reads until update, then switches to write. This is the default.
CLIENT_USAGE_READ_ONLY—Client is not allowed to do updates.
CLIENT_USAGE_READ_WRITE—Client can do both reads and updates.
CLIENT_USAGE_REACQUIRE_INSTANCE_LOCK—Client is allowed to overwrite this local repository even if a lock file exists, as long as it’s the same user.
CLIENT_USAGE_FORCE_INSTANCE_LOCK—Client is allowed to overwrite this local repository even if a lock file exists.
Examples are given below:
./instances/myInst.dat:userName=deborah
c:/tibco/repository/instances/myInst.dat:urlFile=c:/tibco/repository/props/deborah
myProj.dat
myProj
myProj/myrepo.dat
How Adapters Access Configuration Information
This section explains how a custom adapter can access configuration information.
MApp and MClassRegistry
Upon startup, MApp creates an MClassRegistry object that the custom adapter can use to access the information in the project repository. For example:
In addition, MApp creates metadata description classes for metadata objects and their attributes. The custom adapter can access that information as needed. See Metadata Description Classes.
MProperties
By default, MApp creates an MProperties instance that encapsulates access to the adapter instance description object.
In the following C++ code fragment, the adapter creates a publisher using the configuration URL and the subject specified in the adapter instance definition. Note how the configuration URL is included as the first argument to getValue().

 
if (!pMProperties->getValue("zapadapter/zapconnection/instance", m_sInstanceId))
m_sInstanceId = "zap:112";
 
if (!pMProperties->getValue("zapadapter/zapconnection/hostname", m_sHostName))
m_sHostName = "hostile";
 
if (!pMProperties->getValue("zapadapter/zapconnection/port", m_iPort))
m_iPort = 8000;

 
A Java SDK custom adapter uses similar methods.
Configuration Classes
A custom adapter uses configuration classes to access configuration information. The following classes are defined in both the C++ and the Java API:
MProperties—Custom adapters call methods in an instance of this class to retrieve property information.
MPropertiesEnumerator—Allows you to iterate through the MProperties name/value pairs.
MPropertiesRegistry—Manages all MProperties instances. Allows you to commit and roll back changes and create new MProperties instances for project repositories.
MConfigurationUtilities—Allows specialized custom adapters direct control over the creation of components and metadata from configuration information. This class should only be used under certain circumstances.
The Java SDK has the following classes for encapsulating information retrieved from an MProperties instance: MPropertyElement, MPropertyAttribute, and MPropertyText. This helps custom adapters retrieve information from MProperties.
See MProperties.elements() TIBCO Adapter SDK API Referencefor more information.
 
MProperties.elements() Example
 
The following example shows how to enumerate an MProperties object.
/* get the configuration properties from MApp */
MProperties prop = mapp.getConfigProperties();
Enumeration enum = prop.elements("/private/tibco/adapter");
for (;enum.hasMoreElements();) {
Object o = e.nextElement();
if( o instanceof MPropertyAttribute)
{
MPropertyAttribute a = (MPropertyAttribute)o;
System.out.print(" "+a.getName()+"="+a.getValue() );
}
else if(o instanceof MPropertyText)
{
MPropertyText t = (MPropertyText )o;
System.out.println( t.getText() );
}
else ifo instanceof MPropertyElement)
{
MPropertyElement t = (MPropertyElement)o;
System.out.println
                     "This is PropertyElement - has to recursively
                      get the enumeration again");
}
else
System.out.println("Should never happen");
}

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