While upgrading our TDI 6.0 installation to TDI 7.1, you may find yourself in one of the following scenarios:
TDI Server version> | 6.0 | 6.1 |
---|---|---|
6.0 | OK | In most cases porting the client to 6.1 is required - see the "Guidelines for porting a TDI 6.0 Server API client to use a TDI 7.1 server" section |
6.1 | OK with some caveats - see the "Guidelines for implementing a Server API client capable of working with both TDI 6.0 and TDI 7.1 servers" section | OK |
Probably the most significant change in the TDI 7.1 Server API is the way configurations are edited. For more information on editing configurations in TDI 7.1 see the "Using the Server API -> Editing Configurations" section.
Server API changes in TDI 7.1 relevant to porting a TDI 6.0 Server API client:
Another reason to rework a TDI 6.0 client is to benefit from the functionality introduced in TDI 7.1:
Another important consideration while porting a TDI 6.0 client is the usage of serializable classes. More details can be found in the "Using serializable classes" section. A major part of the serializable classes used by the Server API are the TDI config interface classes. New serializable classes are listed in "Table 82 - New Serializable classes/interfaces". A complete reference of the config interfaces can be found in the JavaDocs provided with TDI.
If the TDI 6.0 client does not use config editing and there is no requirement to use the new TDI 7.1 Server API features the TDI 6.0 client does not need to be modified.
Since the enhancements in the Server API are done in a backward compatible manner it is possible a Server API client application to use all TDI 6.0 features against a TDI 6.0 Server and also use all new TDI 7.1 features against a TDI 7.1 Server. This can be accomplished by having the Server API client check the TDI server version and then execute the appropriate version specific code accordingly. An example is available in the "Checking the TDI server version" section.
There are two primary ways of sharing data between the Server API client and the TDI server:
In this case the Server API client will use remote object stubs generated from the TDI 7.1 version of the remote classes. These stubs contain all methods existing in the TDI 6.0 version of the remote classes as well as the methods introduced in TDI 7.1 (as they are described in "Table 79 - New Methods"):
The Server API serializable classes as well as the TDI serializable classes have evolved from TDI 6.0 to TDI 7.1. Thus these classes are different in TDI 6.0 and in TDI 7.1. Nevertheless these classes have evolved in a backward compatible way from a serialization perspective. This means that the TDI 6.0 serializable classes can interoperate with the TDI 7.1 serializable classes through the Java RMI engine.
The Java RMI engine determines whether serializable classes are compatible by checking the class serial version UID - if the class serial version UID of two classes are identical then the RMI engine considers these two classes compatible. The serial version UIDs of the serializable classes in TDI can be found in "Table 83 - serialVersionUID for serializable classes". Since the TDI 7.1 serializable classes are compatible with the TDI 6.0 serializable classes the serial version UIDs of these classes have not changed.
"Table 82 - New Serializable classes/interfaces" lists classes and interfaces introduced in TDI 7.1. Since these classes and interfaces are not available in TDI 6.0 they cannot be used against a TDI 6.0 server. The TDI JavaDocs should be referred to for more detailed information on method signature changes of serializable classes in both releases. Methods which are not available in TDI 6.0 cannot be used against a TDI 6.0 server.
If the Server API client uses third party or custom user serializable classes then the best approach would be to ensure that these classes are identical on the server and on the client. If for any reason the serializable classes are different (but compatible) versions of the same class then the client still can work if both versions are set the same serialVersionUID. More information on maintaining and evolving serializable classes can be found at:
http://java.sun.com/j2se/1.5.0/docs/api/java/io/Serializable.html
http://java.sun.com/j2se/1.5.0/docs/guide/serialization/spec/serialTOC.html
http://www-03.ibm.com/developerworks/blogs/page/woolf?entry=serialization_and_serial_version_uid
Config editing in TDI 7.1 is very different from config editing in TDI 6.0. That is why special care must be taken when coding editing TDI configs for both TDI 6.0 and TDI 7.1 servers. This code is TDI version-specific. That is why the code needs to be branched by checking the TDI server version as described in the "Checking the TDI server version" section.
The username/password based authentication mechanism and the LDAP authentication mechanism are not supported on TDI 6.0. That is why the createSession (String aUserName, String aPassword) method of the com.ibm.di.api.remote.SessionFactory interface will fail if invoked against a TDI 6.0 server.
Usually most of the Server API client code will be common for TDI 6.0 and TDI 7.1 servers. Sometimes, however, TDI 6.0- or TDI 7.1-specific code could be needed. These version-specific portions of code require checking the server version. Below is a code sample which demonstrates how the TDI server version can be retrieved and used.
import com.ibm.di.api.remote.Session; import com.ibm.di.api.remote.ServerInfo; ... ServerInfo serverInfo = session.getServerInfo(); if (serverInfo == null) { throw new Exception("Server version information is not available!"); } String serverVersion = serverInfo.getServerVersion(); if (serverVersion.startsWith("6.1")) { // TDI 6.1 specific code } else if (serverVersion.startsWith("6.0")) { // TDI 6.0 specific code } else { throw new Exception("Unsupported TDI server version: " + serverVersion); }
Name | Description |
---|---|
SystemQueue | Server API access to SystemQueue |
TDIProperties | Wrapper for External Property Stores |
TombstoneManager | Access to Tombstones read and delete |
Name | Description |
---|---|
AssemblyLine | |
String getGlobalUniqueID () | Returns AssemblyLine GUID. The GUID is a string value that is unique for each component ever created by a particular TDI Server. |
ConfigInstance | |
String getGlobalUniqueID () | Returns the Config Instance GUID. The GUID is a string value that is unique for each component ever created by a particular TDI Server. |
String[] getConnectorPoolNames () | Returns the names of all Connector Pools in the Config Instance. |
int getConnectorPoolSize (String aConnectorPoolName) | Returns the size of the specified Connector Pool. |
int getConnectorPoolFreeNum (String aConnectorPoolName) | Returns the number of free Connectors in the specified Connector Pool. |
PoolDefConfig getConnectorPoolConfig (String aConnectorPoolName) | Returns the Connector Pool configuration object. |
int purgeConnectorPool (String aConnectorPoolName) | Unused Connectors will be released so that the Pool is shrunk to its minimum size. |
TDIProperties getTDIProperties() | Returns the TDIProperties object associated with the current configuration. |
Session | |
void shutDownServer (int aExitCode) | Shuts down the TDI Server with the specified exit code. |
TombstoneManager getTombstoneManager () | Returns the TombstoneManager object. Tombstones can be queried and cleared through this object. |
boolean isSSLon () | Checks if current session is over SSL. |
boolean releaseConfigurationLock(String aRelativePath) | Administratively releases the lock of the specified configuration. This call can be only executed by users with the admin role. |
boolean undoCheckOut(String aRelativePath) | Releases the lock on the specified configuration, thus aborting all changes being done. This call can only be executed from a user that has previously checked out the configuration and only if the configuration lock has not timed out. |
ArrayList listConfigurations(String aRelativePath) | Returns a list of the file names of all configurations in the specified folder. The configurations file paths returned are relative to the Server configuration codebase folder. |
ArrayList listFolders(String aRelativePath) | Returns a list of the child folders of the specified folder. |
ArrayList listAllConfigurations() | Returns a list of the file names of all configurations in the directory subtree of the Server configuration codebase folder. The configurations file paths returned are relative to the TDI Server configuration codebase folder. |
MetamergeConfig checkOutConfiguration (String aRelativePath) | Checks out the specified configuration. Returns the MetamergeConfig object representing the configuration and locks that configuration on the Server. |
MetamergeConfig checkOutConfiguration (String aRelativePath, String aPassword) | Checks out the specified password protected configuration. Returns the MetamergeConfig object representing the configuration and locks that configuration on the Server. |
ConfigInstance checkOutConfigurationAndLoad (String aRelativePath) | Checks out the specified configuration and starts a temporary Config Instance on the Server. |
ConfigInstance checkOutConfigurationAndLoad (String aRelativePath, String aPassword) | Checks out the specified configuration and starts a temporary Config Instance on the Server. |
void checkInConfiguration (MetamergeConfig aConfiguration, String aRelativePath) | Saves the specified configuration and releases the lock. If a temporary ConfigInstance has been started on check out, it will be stopped as well. |
void checkInAndLeaveCheckedOut (MetamergeConfig aConfiguration, String aRelativePath) | Checks in the specified configuration and leaves it checked out. The timeout for the lock on the configuration is reset. |
void checkInConfiguration (MetamergeConfig aConfiguration, String aRelativePath, boolean aEncrypt) | Encrypts and saves the specified configuration and releases the lock. If a temporary Config Instance has been started on check out, it will be stopped as well. |
MetamergeConfig createNewConfiguration (String aRelativePath, boolean aOverwrite) | Creates a new empty configuration and immediately checks it out. If a configuration with the specified path already exists and the aOverwrite parameter is set to false the operation will fail and an Exception will be thrown. |
ConfigInstance createNewConfigurationAndLoad (String aRelativePath, boolean aOverwrite) | Creates a new empty configuration, immediately checks it out and loads a temporary Config Instance on the Server. If a configuration with the specified path already exists and the aOverwrite parameter is set to false the operation will fail and an Exception will be thrown. |
boolean isConfigurationCheckedOut (String aRelativePath) | Checks if the specified configuration is checked out on the Server. |
void sendCustomNotification (String aType, String aId, Object aData) | Sends a custom, user defined notification to all registered listeners. |
SystemQueue getSystemQueue() | Gets the remote Server API SystemQueue representation object |
String getConfigFolderPath() | Gets the value of the api.config.folder property in the remote server as a complete path. If not set, then returns an empty string. |
Object invokeCustom (String aCustomClassName, String aMethodName, Object[] aParams) | Invokes the specified method from the specified class. |
Object invokeCustom (String aCustomClassName, String aMethodName, Object[] aParamsValue,String[] aParamsClass) | Invokes the specified method from the specified class. |
SessionFactory | |
Session createSession (String aUserName, String aPassword) | Creates a session object with the specified username and password. |
Name | Description |
---|---|
ConfigInstance | |
void setConfiguration (MetamergeConfig aConfiguration) | In TDI 7.1 this method can be invoked only if a particular client has already checked out same config with temporary config instance. |
Name | Description |
---|---|
ConfigInstance | |
void saveConfiguration () | Use CheckIn methods instead of save |
void saveConfiguration (boolean aEncrypt) | Use CheckIn methods instead of save |
void setExternalProperties (ExternalPropertiesConfig aExPropConfig) | Use TDIProperties |
void setExternalProperties (String aKey, ExternalPropertiesConfig aExPropConfig) | Use TDIProperties |
void saveExternalProperties () | Use TDIProperties |
Name | Description |
---|---|
com.ibm.di.api.Tombstone | 5178569311755396746L |
com.ibm.di.api.CIEvent | 5178569311755396746L |
com.ibm.di.config.interfaces.NamespaceEvent | -1857414661726671152L |
com.ibm.di.config.interfaces.OperationConfig | 2715909691453046036L |
com.ibm.di.config.interfaces.PoolDefConfig | -1252371938517765606L |
com.ibm.di.config.interfaces.PoolInstanceConfig | 5594919717769030291L |
com.ibm.di.config.interfaces.PropertyManager | 4280805548502266432L |
com.ibm.di.config.interfaces.PropertyStoreConfig | -2620929677558833640L |
com.ibm.di.config.interfaces.ReconnectConfig | -7935628947261477628L |
com.ibm.di.config.interfaces.TDIProperties | -3361471837888677277L |
com.ibm.di.config.interfaces.TDIPropertyStore | 198251115520372634L |
com.ibm.di.config.interfaces.TombstonesConfig | -3260102686391332434L |
Name | Status | serialVersionUID |
---|---|---|
com.ibm.di.api.ALEvent | backward compatible | 5631772256973692972L |
com.ibm.di.config.base.ALMappingConfigImpl | backward compatible | 2712493657450710788L |
com.ibm.di.server.ALState | backward compatible | 669938312260868491L |
com.ibm.di.config.base.AssemblyLineConfigImpl | backward compatible | 2715909691453046036L |
com.ibm.di.entry.Attribute | backward compatible | 6675881744901860329L |
com.ibm.di.config.base.AttributeMapConfigImpl | backward compatible | -2619015538178665684L |
com.ibm.di.entry.AttributeValue | backward compatible | 100100L |
com.ibm.di.config.base.BaseConfigurationImpl | known issue - see the Known issues section | -7316979979253125005L |
com.ibm.di.config.base.BranchConditionImpl | backward compatible | -4091773233583817912L |
com.ibm.di.config.base.BranchingConfigImpl | backward compatible | -1013588884381133944L |
com.ibm.di.config.base.CallConfigImpl | backward compatible | -4697458497835329096L |
com.ibm.di.config.base.CallParamConfigImpl | backward compatible | 5788021154714741767L |
com.ibm.di.config.base.CheckpointConfigImpl | backward compatible | -8342369881523468483L |
com.ibm.di.config.base.ConfigCache | backward compatible | -3311255731504174416L |
com.ibm.di.config.base.ConfigStatistics | backward compatible | -1271645457384911249L |
com.ibm.di.config.base.ConnectorConfigImpl | backward compatible | 4093376456212230000L |
com.ibm.di.config.base.ConnectorSchemaConfigImpl | backward compatible | 930161291800752910L |
com.ibm.di.config.base.ConnectorSchemaItemConfigImpl | backward compatible | -1665598194757295769L |
com.ibm.di.config.base.ContainerConfigImpl | backward compatible | -4134004409592694052L |
com.ibm.di.config.base.DeltaConfigImpl | backward compatible | -7250128484588024017L |
com.ibm.di.api.DIEvent | backward compatible | -8664533477452491219L |
com.ibm.di.entry.Entry | backward compatible | -5961424529378625729L |
com.ibm.di.config.interfaces.ExternalPropertiesDelegator | known issue - see the Known issues section | 7725187425731381660L |
com.ibm.di.config.base.ExternalPropertiesImpl | backward compatible | -5837658758525300221L |
com.ibm.di.config.base.FormConfigImpl | backward compatible | -8761349695805705052L |
com.ibm.di.config.base.FormItemConfigImpl | backward compatible | -7825109041707716857L |
com.ibm.di.config.base.FunctionConfigImpl | backward compatible | 5778585850194005910L |
com.ibm.di.config.interfaces.GlobalRef | backward compatible | 366178307603105225L |
com.ibm.di.config.base.HookConfigImpl | backward compatible | -1300997546910640256L |
com.ibm.di.config.base.HooksConfigImpl | backward compatible | -9160883008989377612L |
com.ibm.di.config.interfaces.InheritanceLoopException | backward compatible | -5977834080357995975L |
com.ibm.di.config.base.InheritConfigImpl | backward compatible | 9015532163983199487L |
com.ibm.di.config.base.InstanceConfigImpl | backward compatible | -7052997089129596762L |
com.ibm.di.config.base.LibraryConfigImpl | backward compatible | -6737181973806281819L |
com.ibm.di.config.base.LinkCriteriaConfigImpl | backward compatible | -9206856536172011821L |
com.ibm.di.config.base.LinkCriteriaItemImpl | backward compatible | -952539248920610452L |
com.ibm.di.config.base.LogConfigImpl | backward compatible | 3371411072185625170L |
com.ibm.di.config.base.LogConfigItemImpl | backward compatible | 6299750464788808971L |
com.ibm.di.config.base.LoopConfigImpl | backward compatible | -8174541074510481418L |
com.ibm.di.config.base.MetamergeConfigImpl | backward compatible | -3363695330685967904L |
com.ibm.di.config.xml.MetamergeConfigXML | backward compatible | -4403169711579029765L |
com.ibm.di.config.base.MetamergeFolderImpl | backward compatible | 6107586753523140220L |
com.ibm.di.config.base.NamespaceConfigImpl | backward compatible | 986964857890827079L |
com.ibm.di.config.base ParserConfigImpl | backward compatible | 5497221494799800099L |
com.ibm.di.config.base.PropertyConfigImpl | backward compatible | -2620929677558833640L |
com.ibm.di.config.base.RawConnectorConfigImpl | backward compatible | 8439049716964119460L |
com.ibm.di.config.base.SandboxConfigImpl | backward compatible | -399320124155373314L |
com.ibm.di.config.base.SchemaConfigImpl | backward compatible | 1778816095104785134L |
com.ibm.di.config.base.SchemaItemConfigImpl | backward compatible | 5168801947811376566L |
com.ibm.di.config.base.ScriptConfigImpl | backward compatible | -7747686242551793890L |
com.ibm.di.api.remote.impl.rmi.SSLRMIClientSocketFactory | backward compatible | 5083017546031420384L |
com.ibm.di.server.TaskCallBlock | backward compatible | 115072761837771375L |
com.ibm.di.server.TaskStatistics | backward compatible | 2098518046376889585L |
com.ibm.di.api.remote.impl.rmi.RMISocketFactory | backward compatible | -3200652858929712303L |
The com.ibm.di.config.interfaces.ExternalPropertiesDelegator class is the implementation class of the com.ibm.di.config.interfaces.ExternalPropertiesConfig interface. The com.ibm.di.config.interfaces.ExternalPropertiesDelegator class also extends the com.ibm.di.config.base.BaseConfigurationImpl class.
Server API client code deals with interfaces and not classes, that is why the ExternalPropertiesDelegator class is not directly referenced in the Server API client source code. The limitation is that while a TDI 6.0 client can retrieve an ExternalPropertiesConfig object from a TDI 6.0 server, this client cannot modify the external properties on the server by calling the setExternalProperties(String aKey, ExternalPropertiesConfig aExPropConfig) or the setExternalProperties(ExternalPropertiesConfig aExPropConfig) on a config instance object (com.ibm.di.api.remote.ConfigInstance). If one of these methods is invoked from a TDI 7.1 client against a TDI 6.0 server it will fail.
The same issue as the above one discussed for com.ibm.di.config.interfaces.ExternalPropertiesDelegator applies to com.ibm.di.config.base.BaseConfigurationImpl as well. (The former is an extension of the latter.)