Websphere MQ Everyplace

com.ibm.mqe.adapters
Class MQeMappingAdapter

java.lang.Object
  |
  +--com.ibm.mqe.MQe
        |
        +--com.ibm.mqe.MQeAdapter
              |
              +--com.ibm.mqe.adapters.MQeMappingAdapter
All Implemented Interfaces:
MQeExceptionCodes

public class MQeMappingAdapter
extends MQeAdapter

An adapter which can be enable MQe code to use long filenames, but maps those long filenames to shorter representation file names (for example 8.3 format) before operations are performed against the file system.

The map of long to short filenames is stored persistently whenever a file is created or deleted using a private adapter configured by default to use an MQeDiskFieldsAdapter. The class name of the private adapter can be changed using system properties described below.

The data passed to the mapping adapter is not stored by the mapping adapter itself. All operations are delegated to a delegate adapter. The class name of the delegate adapter can also be configured using system properties described below.

Filenames passed to this adapter are considered to be logical names, which are converted into physical names for the delegate adapter to use.

A translation table, map, or name space, holds the physical to logical name mappings, where the physical names are known to the delegate adapter, and the logical names are known only to the object that instantiated the MQeMappingAdapter. Thus the MQeMappingAdapter essentially provides a name translation service, where the caller knows of the logical names in the translation table, and the delegate adapter knows of the physical names it manages in its base path.

For example: A logical name might be "C:\MQe\QMgrs\Registry\QMNAME\Queues\QMNAME+AdminQ.MQeReg", and the corresponding physical name might be "A_______.MQE".

When the MQeMappingAdapter receives a request to access a logical name, it uses the transient translation table to resolve the physical name and passes the request off to the delegate adapter. There is a one-to-one relationship between an instance of this class and the delegate instance of an MQeAdapter. However, all delegate adapters use the same translation tables.

Tailoring behaviour of the adapter using java system properties:

This adapter has several pieces of configuration information which can be set using Java system properties. Use of Java System properties effect all instances of the adapter in a particular JVM. These properties are:

com.ibm.mqe.adapters.MQeMappingAdapter.PrivateAdapter.Name

This is the name of the adapter which will be used to write out the mapping table every time it is updated.

A symbolic value of PRIVATE_NAME_KEY is provided for programmatic use.

A default of PRIVATE_NAME_DEFAULT_VALUE will be assumed if this property is not set.

com.ibm.mqe.adapters.MQeMappingAdapter.PrivateAdapter.NameDesc

This is the directory/folder location in which the private adapter will store the translation table used by this adapter. To avoid the names of data files clashing with the name of the mapping file, the value should NOT be the same as that specified using the DELEGATE_NAME_DESC_KEY.

A symbolic value of PRIVATE_NAME_DESC_KEY is provided for programmatic use.

A default of PRIVATE_NAME_DESC_DEFAULT_VALUE will be assumed if this property is not set.

On the 4690 operating system, this value must start with a <DRIVELETTER>:/ string.

com.ibm.mqe.adapters.MQeMappingAdapter.PrivateAdapter.NameTable

This is the name of the translation table that is written by the private adapter each time an open or erase method is called in the mapping adapter and passed to the delegate adapter.

A symbolic value of PRIVATE_NAME_TABLE_KEY is provided for programmatic use.

A default of PRIVATE_NAME_TABLE_DEFAULT_VALUE will be assumed if this property is not set.

com.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.Name

The name of the delegate adapter to which requests to manipulate the physical files are passed. This would normally be an adapter which stores data to a persistent medium.

A symbolic value of DELEGATE_NAME_KEY is provided for programmatic use.

A default value of DELEGATE_NAME_DEFAULT_VALUE will be assumed if this property is not set.

com.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NameDesc

This is the folder/directory location in which the delegate adapter instances will store the physical names referenced by the logical names in the translation table. To avoid the names of data files clashing with the name of the mapping file, the value should NOT be the same as that specified using the PRIVATE_NAME_DESC_KEY

A symbolic value of DELEGATE_NAME_DESC_KEY is provided for programmatic use.

A default of DELEGATE_NAME_DESC_DEFAULT_VALUE will be assumed if this property is not set.

On the 4690 operating system, this value must start with a <DRIVELETTER>:/ string.

com.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NamePrefix

This is the name prefixed to each and every physical name generated from the physical name algorithm. We recommend that this value does not start with a '_' character, or any reserved characters used by the underlying file system. For example '/' '\' or ':'. These are filesystem specific.

A symbolic value of DELEGATE_NAME_PRE_KEY is provided for programmatic use.

A default of DELEGATE_NAME_PRE_DEFAULT_VALUE will be assumed if this property is not set.

com.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NameLength

This is the full length of the first part of the physical names generated by the physical name algorithm, NOT including the name prefix. For example, if a filename must conform to 8.3 standard, and a NamePrefix of MQE_ is used, the maximum NameLength would be 4. A valid NameExtension would be: .MQE Note: there is NO verification of filename validity for a particular filesystem.

A symbolic value of DELEGATE_NAME_LEN_KEY is provided for programmatic use.

A default value of DELEGATE_NAME_LEN_DEFAULT_VALUE is assumed if this property is not set.

com.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NameExtension

This is the name extension for each and every physical name generated from the physical name algorithm. For example, if a filename must conform to 8.3 format, an valid NameExtension would be: .MQE

A symbolic value of DELEGATE_NAME_EXT_KEY is provided for programmatic use.

A default value of DELEGATE_NAME_EXT_DEFAULT_VALUE is assumed if this property is not set.

com.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NameCaseSensitive

This is a switch to determine whether the names generated by the physical name algorithm are folded to upper-case. A value of yes indicates no case conversion will be performed on the physical names, whereas a value of no indicates that all physical names will be converted to upper case.

A symbolic value of DELEGATE_NAME_CASE_KEY is provided for programmatic use.

A default value of DELEGATE_NAME_CASE_DEFAULT_VALUE is assumed if this property is not set.

com.ibm.mqe.adapters.MQeMappingAdapter.Debug

This is a switch to determine whether the adapter should output debugging trace inforomation. A value of true indicates debugging information should be generated. other values indicate that less trace information is generated. Default is false. whereas a value of no indicates that all physical names will be converted to upper case.

Usage Example for a case insensitive 8.3 filename Operating System:

   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NamePrefix=
   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NameLength=8
   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NameExtension=.MQE
   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NameCaseSensitive=no
   

Using the properties above, a name generated by the physical name algorithm could be: A_______.MQE

Usage Example for a case sensitive long filename Operating System:

   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NamePrefix=MQeRegistry_
   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NameLength=4
   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NameExtension=.MQeReg
   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NameCaseSensitive=yes
   

Here, a name generated by the physical name algorithm could be: MQeRegistry_A____.MQeReg

While this could have a limited use in placing all files in a single directory, note that there is no simple method of determining the logical name of the file from the physical name, which is allocated by the physical name generation algorithm sequentially.

Setting MQeMappingAdapter properties:

When invoking a program using a Java runtime program such as "java", "jview" or "jre", you can use all the System properties listed below (the values here are the defaults):

   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.PrivateAdapter.Name=com.ibm.mqe.adapters.MQeDiskFieldsAdapter
   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.PrivateAdapter.NameDesc=C:/PRIVATE.MQE
   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.PrivateAdapter.NameTable=TRANS.TBL
   
   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.Name=com.ibm.mqe.adapters.MQeDiskFieldsAdapter
   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NameDesc=C:/DELEGATE.MQE
   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NamePrefix=
   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NameLength=8
   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NameExtension=.MQE
   -Dcom.ibm.mqe.adapters.MQeMappingAdapter.DelegateAdapter.NameCaseSensitive=no
   

Changing .ini files in the examples so this adapter is used by the registry part of the MQe queue manager:

To configure the adapter into an .ini file used by many MQe examples, you need to adjust the "Adapter" property in the [Registry] section.

For example:

       [Registry]
       (ascii)Adapter=com.ibm.mqe.adapters.MQeMappingAdapter
   

Loading the translation table:

When the mapping adapter is activated it loads the physical to logical translation table using a private instance of an MQeAdapter, and reconstructs the logical to physical name mappings. At this time inconsistencies are reported and resolved.

If a file exists on the file system, but not in the translation table, and the name is a valid name that could be generated by the physical name algorithm, then a warning trace statement is output, and the physical name is marked as unusablel. This is so that the physical name cannot be allocated during the lifetime of the adpater, which would result in the contents of the file being overwritten.

If a physical name exists in the translation table, but not in the filesystem, then a warning trace statement is output, and the physical name is removed, so the translation table and the filesystem are kept as consistent as possible.

Physical names:

The translation table used by the mapping adapter is stored in a location using the NameDesc property concatenated with a file separator and then the NameTable property.

The mapping adapter implements a simple algorithm for generating physical names for passing to the delegate adapters. The algorithm uses a unique identifier to index into an internal table of filesystem specific characters. The charater set is: "_abcdefghijklmnopqrstuvwxyz". The unique identifier references the character set in base 26 where the most significant character is furthest to the right. In addition the reserved character representing 0 (zero) (i.e. '_') is not used to the left of a more significant character. This is best illustrated using some examples:

    0         =>  ________.MQE  
    1         =>  a_______.MQE
    26        =>  z_______.MQE
    27        =>  aa______.MQE 
    28        =>  ba______.MQE  
    20021014  =>  zvbuqa__.MQE
   

Note that indexing starts at 1, so this physical name is never used, this is so that the name prefix the first character in the set, i.e. '_', can be used to put reserved names into the delegate adapter space in the future.

Note also that the 'reserved character', the first in the character set is used to pad the physical names to the value of the NameLength property.

The algorithm does not cycle around the first character to the reserved character in the character set, i.e '_a______.MQE'.

WARNING:

The mapping adapter itself should NOT be used as a delegate adapter since this behavior is undefined, and would result in a circular reference, and a Java Virtual Machine "OutOfMemory" runtime error. (JVM heap/stack overflow)

WARNING:

Using two invocations of the JVM, each using a mapping adapter is practicable providing that both JVMs are configured to use different locations for both private and delegate storage locations. Failure to do this results in undefined behavior and will corrupt and/or lose data.

WARNING:

This adapter is capable of handling MAX_FILES_SUPPORTED files in total. If your solution requires more files than this, use of this adapter may not be appropriate.

See Also:
MQeAdapter, MQeDiskFieldsAdapter

Field Summary
static java.lang.String DELEGATE_NAME_CASE_DEFAULT_VALUE
          The default value used by the adapter if the system property with the key DELEGATE_NAME_CASE_KEY is not specified.
static java.lang.String DELEGATE_NAME_CASE_KEY
          The key used to set and get a java system property.
static java.lang.String DELEGATE_NAME_DEFAULT_VALUE
          The default value used by the adapter if the system property with the key DELEGATE_NAME_KEY is not specified.
static java.lang.String DELEGATE_NAME_DESC_DEFAULT_VALUE
          The default value used by the adapter if the system property with the key DELEGATE_NAME_DESC_KEY is not specified.
static java.lang.String DELEGATE_NAME_DESC_KEY
          The key used to set and get a java system property.
static java.lang.String DELEGATE_NAME_EXT_DEFAULT_VALUE
          The default value used by the adapter if the system property with the key DELEGATE_NAME_EXT_KEY is not specified.
static java.lang.String DELEGATE_NAME_EXT_KEY
          The key used to set and get a java system property.
static java.lang.String DELEGATE_NAME_KEY
          The key used to set and get a java system property.
static java.lang.String DELEGATE_NAME_LEN_DEFAULT_VALUE
          The default value used by the adapter if the system property with the key DELEGATE_NAME_LEN_KEY is not specified.
static java.lang.String DELEGATE_NAME_LEN_KEY
          The key used to set and get a java system property.
static java.lang.String DELEGATE_NAME_PRE_DEFAULT_VALUE
          The default value used by the adapter if the system property with the key DELEGATE_NAME_PRE_KEY is not specified.
static java.lang.String DELEGATE_NAME_PRE_KEY
          The key used to set and get a java system property.
static int MAX_FILES_SUPPORTED
          The maximum number of files this adapter can support.
static java.lang.String PRIVATE_NAME_DEFAULT_VALUE
          The default value used by the adapter if the system property with the key PRIVATE_NAME_KEY is not specified.
static java.lang.String PRIVATE_NAME_DESC_DEFAULT_VALUE
          The default value used by the adapter if the system property with the key PRIVATE_NAME_DESC_KEY is not specified.
static java.lang.String PRIVATE_NAME_DESC_KEY
          The key used to set and get a java system property.
static java.lang.String PRIVATE_NAME_KEY
          The key used to set and get a java system property.
static java.lang.String PRIVATE_NAME_TABLE_DEFAULT_VALUE
          The default value used by the adapter if the system property with the key PRIVATE_NAME_TABLE_KEY is not specified.
static java.lang.String PRIVATE_NAME_TABLE_KEY
          The key used to set and get a java system property.
 
Fields inherited from class com.ibm.mqe.MQeAdapter
MQe_Adapter_BYTECOUNTS, MQe_Adapter_EXISTS, MQe_Adapter_FILENAME, MQe_Adapter_FILTER, MQe_Adapter_LIST, MQe_Adapter_READ, MQe_Adapter_RENAME, MQe_Adapter_RETRIES, MQe_Adapter_UPDATE, MQe_Adapter_WRITE
 
Fields inherited from class com.ibm.mqe.MQe
Admin_Queue_Name, Admin_Reply_Queue_Name, copyright, DeadLetter_Queue_Name, Event_Activate, Event_Attribute, Event_Authenticate, Event_Close, Event_Logoff, Event_Logon, Event_MiniCert_Validate, Event_Queue, Event_QueueManager, Event_UserBase, JMS_Version, MQ_Headers, MQe_Log_Audit_Failure, MQe_Log_Audit_Success, MQe_Log_Error, MQe_Log_Information, MQe_Log_Success, MQe_Log_Warning, Msg_BackoutCount, Msg_CorrelID, Msg_ExpireTime, Msg_LockID, Msg_MsgID, Msg_OriginQMgr, Msg_Priority, Msg_ReplyToQ, Msg_ReplyToQMgr, Msg_Resend, Msg_Style, Msg_Style_Datagram, Msg_Style_Reply, Msg_Style_Request, Msg_Time, Msg_WrapMsg, sccsid, System_Default_Queue_Name, version
 
Fields inherited from interface com.ibm.mqe.MQeExceptionCodes
Except_Active, Except_AdapterException, Except_AdapterMissingRemoteAddress, Except_Admin_ActionNotSupported, Except_Admin_InvalidField, Except_Admin_NotAdminMsg, Except_AdminAction, Except_Authenticate, Except_BadRequest, Except_BridgeListener, Except_Chnl_Attributes, Except_Chnl_ID, Except_Chnl_Limit, Except_Chnl_Overrun, Except_Closed, Except_Con_AdapterRequired, Except_Con_AliasAlreadyExists, Except_Con_AlreadyExists, Except_Con_InvalidName, Except_Connect_Failure, Except_ConnectonType, Except_Cryptor, Except_Data, Except_Duplicate, Except_JmxProperties, Except_Listener, Except_MessageStore, Except_MiniCertReg_ActivateFailed, Except_MiniCertReg_BadPIN, Except_MiniCertReg_NotOpen, Except_NotActive, Except_NotAllowed, Except_NotFound, Except_NotSupported, Except_PrivateReg_ActivateFailed, Except_PrivateReg_BadPIN, Except_PrivateReg_NotOpen, Except_PublicReg_ActivateFailed, Except_PublicReg_InvalidAddress, Except_PublicReg_InvalidRequest, Except_Q_Full, Except_Q_InvalidName, Except_Q_InvalidPriority, Except_Q_MsgTooLarge, Except_Q_NoMatchingMsg, Except_Q_TargetRegistryRequired, Except_QMgr_Activated, Except_QMgr_AlreadyExists, Except_QMgr_InvalidQMgrName, Except_QMgr_InvalidQName, Except_QMgr_NotActive, Except_QMgr_NotBridgeEnabled, Except_QMgr_NotConfigured, Except_QMgr_QDoesNotExist, Except_QMgr_QExists, Except_QMgr_QNotEmpty, Except_QMgr_RegistryDataVersion, Except_QMgr_UnknownQMgr, Except_QMgr_WrongQType, Except_Reg_AddFailed, Except_Reg_AlreadyExists, Except_Reg_AlreadyOpen, Except_Reg_CRTKeyDecFailed, Except_Reg_CRTKeySignFailed, Except_Reg_DeleteFailed, Except_Reg_DeleteRegistryFailed, Except_Reg_DoesNotExist, Except_Reg_InvalidSession, Except_Reg_ListFailed, Except_Reg_NotDefined, Except_Reg_NotSecure, Except_Reg_NullName, Except_Reg_OpenFailed, Except_Reg_ReadFailed, Except_Reg_RenameFailed, Except_Reg_ResetPINFailed, Except_Reg_SearchFailed, Except_Reg_UpdateFailed, Except_RemoteException, Except_Rule, Except_S_BadIntegrity, Except_S_BadSubject, Except_S_CertificateExpired, Except_S_Cipher, Except_S_InvalidAttribute, Except_S_InvalidSignature, Except_S_MiniCertNotAvailable, Except_S_MissingSection, Except_S_NoPresetKeyAvailable, Except_S_RegistryNotAvailable, Except_Stopped, Except_Syntax, Except_TimeOut, Except_Transporter, Except_TriggerTransmission, Except_Trnsport_QMgr, Except_Trnsport_Request, Except_Type, Except_UdpipAdapterStateException, Except_UdpipAdapterTimeOut, Except_UdpipAdapterUnableToConfirmSuccess, Except_UnCoded, Except_Uncontactable_DontTransmit
 
Constructor Summary
MQeMappingAdapter()
           
 
Methods inherited from class com.ibm.mqe.MQeAdapter
activate, close, control, open, read, readObject, writeObject
 
Methods inherited from class com.ibm.mqe.MQe
abbreviate, alias, asciiToByte, byteToAscii, byteToHex, byteToHex, byteToInt, byteToLong, byteToShort, byteToUnicode, fileSeparator, getEventLogHandler, hexToAscii, hexToByte, intToByte, isCLDC, loadClass, loadObject, log, setEventLogHandler, setLoader, sliceByteArray, type, unicodeToByte, uniqueValue
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DELEGATE_NAME_KEY

public static final java.lang.String DELEGATE_NAME_KEY
The key used to set and get a java system property. As described in the class header.

See Also:
Constant Field Values

DELEGATE_NAME_DEFAULT_VALUE

public static final java.lang.String DELEGATE_NAME_DEFAULT_VALUE
The default value used by the adapter if the system property with the key DELEGATE_NAME_KEY is not specified.

See Also:
Constant Field Values

DELEGATE_NAME_DESC_KEY

public static final java.lang.String DELEGATE_NAME_DESC_KEY
The key used to set and get a java system property. As described in the class header.

See Also:
Constant Field Values

DELEGATE_NAME_DESC_DEFAULT_VALUE

public static final java.lang.String DELEGATE_NAME_DESC_DEFAULT_VALUE
The default value used by the adapter if the system property with the key DELEGATE_NAME_DESC_KEY is not specified.


DELEGATE_NAME_PRE_KEY

public static final java.lang.String DELEGATE_NAME_PRE_KEY
The key used to set and get a java system property. As described in the class header.

See Also:
Constant Field Values

DELEGATE_NAME_PRE_DEFAULT_VALUE

public static final java.lang.String DELEGATE_NAME_PRE_DEFAULT_VALUE
The default value used by the adapter if the system property with the key DELEGATE_NAME_PRE_KEY is not specified.

See Also:
Constant Field Values

DELEGATE_NAME_LEN_KEY

public static final java.lang.String DELEGATE_NAME_LEN_KEY
The key used to set and get a java system property. As described in the class header.

See Also:
Constant Field Values

DELEGATE_NAME_LEN_DEFAULT_VALUE

public static final java.lang.String DELEGATE_NAME_LEN_DEFAULT_VALUE
The default value used by the adapter if the system property with the key DELEGATE_NAME_LEN_KEY is not specified.

See Also:
Constant Field Values

DELEGATE_NAME_EXT_KEY

public static final java.lang.String DELEGATE_NAME_EXT_KEY
The key used to set and get a java system property. As described in the class header.

See Also:
Constant Field Values

DELEGATE_NAME_EXT_DEFAULT_VALUE

public static final java.lang.String DELEGATE_NAME_EXT_DEFAULT_VALUE
The default value used by the adapter if the system property with the key DELEGATE_NAME_EXT_KEY is not specified.

See Also:
Constant Field Values

DELEGATE_NAME_CASE_KEY

public static final java.lang.String DELEGATE_NAME_CASE_KEY
The key used to set and get a java system property. As described in the class header.

See Also:
Constant Field Values

DELEGATE_NAME_CASE_DEFAULT_VALUE

public static final java.lang.String DELEGATE_NAME_CASE_DEFAULT_VALUE
The default value used by the adapter if the system property with the key DELEGATE_NAME_CASE_KEY is not specified.

See Also:
Constant Field Values

PRIVATE_NAME_KEY

public static final java.lang.String PRIVATE_NAME_KEY
The key used to set and get a java system property. As described in the class header.

See Also:
Constant Field Values

PRIVATE_NAME_DEFAULT_VALUE

public static final java.lang.String PRIVATE_NAME_DEFAULT_VALUE
The default value used by the adapter if the system property with the key PRIVATE_NAME_KEY is not specified.

See Also:
Constant Field Values

PRIVATE_NAME_DESC_KEY

public static final java.lang.String PRIVATE_NAME_DESC_KEY
The key used to set and get a java system property. As described in the class header.

See Also:
Constant Field Values

PRIVATE_NAME_DESC_DEFAULT_VALUE

public static final java.lang.String PRIVATE_NAME_DESC_DEFAULT_VALUE
The default value used by the adapter if the system property with the key PRIVATE_NAME_DESC_KEY is not specified.


PRIVATE_NAME_TABLE_KEY

public static final java.lang.String PRIVATE_NAME_TABLE_KEY
The key used to set and get a java system property. As described in the class header.

See Also:
Constant Field Values

PRIVATE_NAME_TABLE_DEFAULT_VALUE

public static final java.lang.String PRIVATE_NAME_TABLE_DEFAULT_VALUE
The default value used by the adapter if the system property with the key PRIVATE_NAME_TABLE_KEY is not specified.

See Also:
Constant Field Values

MAX_FILES_SUPPORTED

public static final int MAX_FILES_SUPPORTED
The maximum number of files this adapter can support.

See Also:
Constant Field Values
Constructor Detail

MQeMappingAdapter

public MQeMappingAdapter()

Websphere MQ Everyplace