|
Websphere MQ Everyplace | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--com.ibm.mqe.MQe | +--com.ibm.mqe.MQeAdapter | +--com.ibm.mqe.adapters.MQeMappingAdapter
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
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
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
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
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
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
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
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
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
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
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.
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 |
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 |
public static final java.lang.String DELEGATE_NAME_KEY
public static final java.lang.String DELEGATE_NAME_DEFAULT_VALUE
DELEGATE_NAME_KEY
is not specified.
public static final java.lang.String DELEGATE_NAME_DESC_KEY
public static final java.lang.String DELEGATE_NAME_DESC_DEFAULT_VALUE
DELEGATE_NAME_DESC_KEY
is not specified.
public static final java.lang.String DELEGATE_NAME_PRE_KEY
public static final java.lang.String DELEGATE_NAME_PRE_DEFAULT_VALUE
DELEGATE_NAME_PRE_KEY
is not specified.
public static final java.lang.String DELEGATE_NAME_LEN_KEY
public static final java.lang.String DELEGATE_NAME_LEN_DEFAULT_VALUE
DELEGATE_NAME_LEN_KEY
is not specified.
public static final java.lang.String DELEGATE_NAME_EXT_KEY
public static final java.lang.String DELEGATE_NAME_EXT_DEFAULT_VALUE
DELEGATE_NAME_EXT_KEY
is not specified.
public static final java.lang.String DELEGATE_NAME_CASE_KEY
public static final java.lang.String DELEGATE_NAME_CASE_DEFAULT_VALUE
DELEGATE_NAME_CASE_KEY
is not specified.
public static final java.lang.String PRIVATE_NAME_KEY
public static final java.lang.String PRIVATE_NAME_DEFAULT_VALUE
PRIVATE_NAME_KEY
is not specified.
public static final java.lang.String PRIVATE_NAME_DESC_KEY
public static final java.lang.String PRIVATE_NAME_DESC_DEFAULT_VALUE
PRIVATE_NAME_DESC_KEY
is not specified.
public static final java.lang.String PRIVATE_NAME_TABLE_KEY
public static final java.lang.String PRIVATE_NAME_TABLE_DEFAULT_VALUE
PRIVATE_NAME_TABLE_KEY
is not specified.
public static final int MAX_FILES_SUPPORTED
Constructor Detail |
public MQeMappingAdapter()
|
Websphere MQ Everyplace | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |