Applying Service Version to Tuxedo Applications

This topic contains the following sections:

•

Overview

•	Enabling and Disabling Application Service Versioning

•	Application Service Version Configurations

•	Version Based Routing

•	Resetting the User Configured Service Version Information Using MIB

•	Interoperability

Overview

It is common that the user wants to keep existing functionality but also want to add new functionality into a service as time goes by. To reduce the compatible risk, it is better to provide two different version services with the same service name, one for old functionality, and the other for new functionality. The old client can still use the existing functionality without changing any code while the new client can use the new functionality.

Application Service Versioning feature offer a configuration driven way which can be used by Tuxedo customers to plan, develop, test, scale, and deploy their Tuxedo applications in each stage. The user can use the version to partition current Tuxedo application into different virtual application domains, different virtual machines, and different virtual server groups on current Tuxedo management hierarchy, so as to respond to various of special business access logics and on the other hand satisfy upgrading requirements in non-stop mode.

This feature supports for COBOL application and programming environment without requiring special changes for COBOL environment.

This feature supports FORWARD queue only for /Q. With Application Service Versioning enabled, when a client puts a message into FORWARD queue, the FORWARD queue forwards the queued message to the service that supports the client request version.

Enabling and Disabling Application Service Versioning

You can enable/disable the application service versioning feature using UBB configuration file or MIB.

Enable/Disable Application Service Versioning Using UBB Config File

To enable the application service versioning in UBB configuration file, add the APPVER option to the OPTIONS parameter in *RESOURCES section.

For example:

*RESOURCES

OPTIONS APPVER, LAN

To disable the application service version in UBB configuration file, remove the APPVER option from the OPTIONS parameter in *RESOURCES section.

For example:

*RESOURCES

OPTIONS LAN

Note:

If the application service versioning is disabled, you cannot configure the application service versioning related attributes in *RESOURCE and *GROUP sections.

Enable/Disable Application Service Versioning Using MIB

To enable the application service versioning in MIB, add the APPVER option to TA_OPTIONS in the T_DOMAIN class.

For example:

SRVCNM .TMIB

TA_OPERATION SET

TA_CLASS T_DOMAIN

TA_OPTIONS APPVER,LAN

To disable the application service versioning in MIB, remove the APPVER option from TA_OPTIONS in the T_DOMAIN class.

For example:

SRVCNM .TMIB

TA_OPERATION SET

TA_CLASS T_DOMAIN

TA_OPTIONS LAN

Note:

Before disabling the application service versioning, you should remove the application service versioning related options that were already configured in MIB. For more information, see Resetting the User Configured Service Version Information Using MIB.

Application Service Version Configurations

UBB Config File Configuration

Three attributes, REQUEST_VERSION, VERSION_POLICY, and VERSION_RANGE, are used in configuration files to specify the version and acceptable version range in a configured Tuxedo management entity. These three attributes can be configured in the *GROUPS and *RESOURCES section of the UBB configuration file, as shown in Listing 16‑1

For more information, see UBBCONFIG(5)in Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference in the Oracle Tuxedo Reference Guide.

Listing 16‑1 UBB Config File Application Service Version Configuration

*RESOURCES
DOMAINID LOCALDOM
OPTIONS LAN,APPVER
REQUEST_VERSION 1 VERSION_RANGE "1-2"
*GROUPS
GRP1 GRPNO=1 REQUEST_VERSION=2
VERSION_POLICY="PROPAGATE"
GRP2 GRPNO=2 VERSION_RANGE="3-4"
GRP3 GRPNO=3 REQUEST_VERSION=3 VERSION_RANGE="1-3"
DMGRP GRPNO=4 LMID=SITE1
GWGRP GRPNO=5 LMID=SITE1
WSGRP GRPNO=6 LMID=SITE1 REQUEST_VERSION=4
JGRP GRPNO=7 LMID=SITE1 REQUEST_VERSION=3
*SERVERS
SERVER1 SVRGRP=GRP1
SERVER2 SVRGRP=GRP2
SERVER3 SVRGRP=GRP3
DMADM SRVGRP=DMGRP
GWADM SRVGRP=GWGRP
GWTDOMAIN SRVGRP=GWGRP
WSL SRVGRP=WSGRP
JSL SRVGRP=JGRP

 

Take Listing 16‑1 for an example, application service version has the following rules:

•

A server inherits the REQUEST_VERSION attribute from the group it belongs to. When a server advertises services, the services inherit version attributes from the group, to which the server belongs. If there is no version attribute value specified to the group, they will inherit upward from the attributes specified in *RESOURCES section. Based on this rule:

•	When server1 advertises SVC2 and SVC3, the REQUEST_VERSION, VERSION_RANGE, and VERSION_POLICY of SVC2 and SVC3 are 2, “1-2”, and PROPAGATE, respectively.

•	When server2 advertises SVC1, SVC2, and SVC3, the REQUEST_VERSION, VERSION_RANGE, and VERSION_POLICY of SVC1, SVC2, and SVC3 are 1, “3-4”, and non-PROPAGATE, respectively.

•	When server3 advertises SVC1 and SVC2, the REQUEST_VERSION, VERSION_RANGE, and VERSION_POLICY of SVC1 and SVC2 are 3, "1-3", and non-PROPAGATE, respectively.

•	If a native client joins the application without specifying the group name, its REQUEST_VERSION is 1.

•	If a native client joins the application with a specific group name, such as GRP3, its REQUEST_VERSION is 3.

•	If a /WS client joins the application, its REQUEST_VERSION is determined by the WSL, whose REQUEST_VERSION is 4 according to the UBB config file. So the REQUEST_VERSION of the /WS client is 4.

•	If a JOLT client joins the application, its REQUEST_VERSION is determined by the JSL, whose REQUEST_VERSION is 3 according to the UBB config file. So the REQUEST_VERSION of the JOLT client is 3.

Domain Config File Configuration

Listing 16‑2 shows a domain configuration file application service version configuration example.

Listing 16‑2 Domain Configuration File Application Service Version Configuration

*DM_LOCAL
LOCALDOM TYPE=TDOMAIN
DOMAINID="LOCALDOM"
*DM_REMOTE
REMOTEDOM1 TYPE=TDOMAIN
DOMAINID= "DOM1" MTYPE="Linux"
REMOTEDOM2 TYPE=TDOMAIN
DOMAINID= "DOM2" MTYPE="Linux"
REQUEST_VERSION=4
*DM_IMPORT
R_SVC1 RDOM= REMOTEDOM1 VERSION_RANGE="1-3"
R_SVC2 RDOM= REMOTEDOM2 VERSION_RANGE="4-6"
R_SVC3 RDOM= REMOTEDOM2

 

From Listing 16‑2, the application service version are configured as follows:

•	No REQUEST_VERSION is configured to REMOTEDOM1. Therefore the domain gateway will propagate the request version of all the requests come from REMOTEDOM1 without changing the incoming request version.

•	The REQUEST_VERSION of the REMOTEDOM2 is configured to 4. Therefore the domain gateway will change the request version of all the requests come from REMOTEDOM2 to 4.

•	The LOCALDOM imports R_SVC1 service from REMOTEDOM1 and specifies the VERSION_RANGE to "1-3". Therefore the VERSION_RANGE of the R_SVC1 service in the LOCALDOM is "1-3".

•	The LOCALDOM imports R_SVC2 service from REMOTEDOM2 and specifies the VERSION_RANGE to "4-6". Therefore the VERSION_RANGE of the R_SVC2 service in the LOCALDOM is "4-6".

•	The LOCALDOM imports R_SVC3 service without specifying VERSION_RANGE. Because the VERSION_RANGE of the imported service is still determined by VERSION_RANGE configuration of the *GROUPS and *RESOURCES, the VERSION_RANGE of the *RESOURCES is "1-2", and the VERSION_RANGE of R_SVC3 is "1-2".

For more information, see UBB Config File Configuration.

Version Based Routing

When the application service versioning feature is enabled, the system dispatches the requests to the service according to both the service name and service version range. We call this mechanism Version Based Routing (VBR). When a service entry matching the requested service name is found, VBR is used for further routing decision.

VBR only does a simple numeric comparison using the current request version number with two boundary values of version range. VBR returns "no entry is found" error to the caller when all the services with the matching name are not allowable for this versioned request.

As a routing mechanism, VBR functions the same as the existing routing mechanisms, like DDR (Data Dependent Routing), TAR (Transaction Affinity Routing), and RAR (Request Affinity Routing).

VBR can work with other routing mechanisms. Oracle Tuxedo chooses the services that match all criteria if there are multiple routing mechanisms. It is recommended you are clear about the interoperability among these routing mechanisms before using them together.

Using Listing 16‑1 as an illustration:

•	Suppose server3 needs to call SVC2 during the initializing period, so the candidate services are:

Server1:SVC2 1-2

Server2:SVC2 3-4

Since the REQUEST_VERSION of server3 configured in Listing 16‑1 is 3, the server3 will call Server2:SVC2.

•	Suppose the native client needs to call SVC3, so the candidate services are:

Server1:SVC3 1-2

Server2:SVC3 3-4

Since the REQUEST_VERSION of the native client configured in Listing 16‑1 is 1, the native client will call Server1:SVC3

•	Suppose the native client calls Server1:SVC1 and Server1:SVC1 needs to call SVC3, so the candidate services are:

Server2:SVC3 3-4

Server3:SVC3 1-3

As configured in Listing 16‑1, the Server1:SVC1 will propagate the incoming REQUEST_VERSION which is 1, as a result the REQUEST_VERSION of Server1:SVC1 will become to 1, rather than its own REQUEST_VERSION 2, therefore the Server1:SVC1 will call Server3:SVC3

•	If a request comes from REMOTEDOM2, suppose the original REQUEST_VERSION is 6, then the REQUEST_VERSION of the incoming request is changed to 4.

•	If a request comes from REMOTEDOM1, suppose the original REQUEST_VERSION is 2, then the REQUEST_VERSION of the incoming request is still 2.

Resetting the User Configured Service Version Information Using MIB

You can configure REQUEST_VERSION, VERSION_RANGE, and VERSION_POLICY in the *GROUPS or *RESOURCES section of UBB config file. The low-level configuration overrides the high level-configuration.

If there is no user-configured service version configuration at any level, the system uses the default value. That causes the result very different for the user configured configuration and default value. If you modify the REQUEST_VERSION, VERSION_RANGE or VERSION_POLICY using MIB, it is the user-configured service version configuration. It is necessary to provide a method to reset this modification to the default value using MIB, otherwise you cannot restore the UBB config file to its original state through MIB operation.

To reset the REQUEST_VERSION, VERSION_RANGE, and VERSION_POLICY to default value, you just need to simply set value as DEFAULT.

For example, modify the REQUEST_VERSION in MIB as shown in Listing 16‑3.

Listing 16‑3 Resetting the User Configured Service Version Information Using MIB

SRVCNM .TMIB
TA_OPERATION SET
TA_CLASS T_GROUP
TA_SRVGRP APPGRP1
TA_GRPNO 1
TA_CURLMID SITE1
TA_REQUEST_VERSION 4
Then the user reset the REQUEST_VERSION to default value through MIB:
SRVCNM .TMIB
TA_OPERATION SET
TA_CLASS T_GROUP
TA_SRVGRP APPGRP1
TA_GRPNO 1
TA_CURLMID SITE1
TA_REQUEST_VERSION DEFAULT

 

Interoperability

You can control how the JCA/WTC/old Tuxedo domain interoperates with the new Tuxedo domain using the domain configuration file, as follows:

•	control the requests coming from JCA/WTC/old Tuxedo domain by setting the REQUEST_VERSION and VERSION_POLICY attributes in the DM_REMOTE section

•	control the requests going to JCA/WTC/old Tuxedo domain by setting VERSION_RANGE in the DM_IMPORT section.

If the request coming from the old Tuxedo domain enters in the Tuxedo 12c domain which has no REQUEST_VERSION configured for the corresponding remote domain, the request version is changed to 0.

The default request version is 0-65535, which means the new domain can call all the imported service from JCA/WTC/old Tuxedo domain by default.

In MP environment, if a local client runs on a machine that is installed the old version Tuxedo, the client can call any version service because there is no version control for the old version Tuxedo.

Likewise, for the /WS or Jolt client connecting to an old version WSL or JSL server, there is no version control for them.