Sample Java registry file

Each of the sample plug-ins written in Java™ provides its own registry file.

The following sections describe the important parts of the registry file and illustrate how to create appropriate entries for your own plug-ins. The examples are taken from the appropriate sample which illustrates the function described.

Programmatic Identifier (ProgID)

Your plug-in is uniquely identified to iSeries™ Navigator by means of a text string of the form <vendor>.<component>, where vendor identifies the vendor who developed the plug-in, and component describes the function being provided. In the examples below, the string IBM.MsgQueueSample3 identifies IBM^® as the vendor, and "MsgQueueSample3" as the description of the function provided by the plug-in. This string is known as the programmatic identifier, or ProgID. It's used throughout the registry file when specifying the function your plug-in provides, and it also names the directory where your plug-in will reside on both the iSeries server and the client workstation.

Globally unique identifiers (GUIDs)

Microsoft^®'s Component Object Model uses 16-byte hex integers to uniquely identify ActiveX implementation classes and interfaces. These integers are known as Globally Unique Identifiers, or GUIDs. GUIDs that identify implementation classes are called CLSIDs (pronounced "class IDs").

For iSeries Navigator components written in Java, you should not define new GUIDs. All Java plug-ins use a set of standard GUIDs that specify the built-in ActiveX server component which manages Java plug-ins. The standard CLSIDs to use are provided in the examples below.

Defining your plug-in's primary attributes

;--------------------------------------------------------------------
; Define the primary registry key for Message Queue Sample 3.

[HKEY_CLASSES_ROOT\IBM.AS400.Network\3RD PARTY EXTENSIONS\IBM.MsgQueueSample3]
"Type"="PLUGIN"
"NLS"="MessageQueuesMRI.dll"
"NameID"=dword:00000001
"DescriptionID"=dword:00000002
"MinimumIMPIRelease"="NONE"
"MinimumRISCRelease"="ANY"
"ProductID"="NONE"
"ServerEntryPoint"="NONE"
"JavaPath"="MsgQueueSample3.jar"
"JavaMRI"="MsgQueueSample3MRI.jar"

Type: If the plug-in adds new folders to the iSeries Navigator hierarchy, the value of this field should be PLUGIN. Otherwise, it should be EXT.

NLS: Identifies the name of the resource DLL that contains locale-dependent resources for the plug-in. In the development version of the registry file, this may be a fully-qualified pathname.

NameID: A double word containing the resource identifier of the text string in the resource DLL which will be used to identify the plug-in in the iSeries Navigator user interface.

DescriptionID: A double word that contains the resource identifier of the text string in the resource DLL. This resource DLL is used to describe the function of the plug-in in the iSeries Navigator user interface.

MinimumIMPIRelease: A 6-character string that identifies the minimum release of i5/OS^® running on IMPI hardware that the plug-in requires. The string should be of the form vvrrmm, where vv is the i5/OS Version, rr is the Release, and mm is the Modification Level. For example, if the plug-in requires Version 3 Release 2 Modification Level 0, the value of this field should be "030200."

If the plug-in does not support any i5/OS release that runs on IMPI hardware (releases prior to Version 3 Release 6), the value of this field should be "NONE." If the plug-in can support any release that runs on IMPI hardware, the value of this field should be "ANY."

MinimumRISCRelease: A 6-character string that identifies the minimum release of i5/OS running on RISC hardware that the plug-in requires. The string should be of the form vvrrmm, where vv is the i5/OS Version, rr is the Release, and mm is the Modification Level. For example, if the plug-in requires Version 3 Release 7 Modification Level 1, the value of this field should be "030701."
If the plug-in does not support any i5/OS release that runs on RISC hardware (Version 3 Release 6 and above), the value of this field should be "NONE." If the plug-in can support any release that runs on RISC hardware, the value of this field should be "ANY."

ProductID: A 7-character string that specifies the product ID of a prerequisite iSeries server licensed program that is required by the plug-in. If the plug-in does not require that a particular licensed program be installed on the iSeries server, the value of this field should be "NONE."
Multiple comma-separated product IDs may be specified if multiple IDs exist for the same product.

ServerEntryPoint: The name of the code DLL that implements the server entry point. This entry point is called by the iSeries Navigator when it needs to determine whether the plug-in is supported on a particular iSeries server. If the plug-in does not implement the entry point, the value of this field should be "NONE." In the development version of the registry file, this may be a fully-qualified pathname.

JavaPath: The classpath string that identifies the location of your plug-in's Java classes. During development of your plug-in, this field might contain the directory paths for the directories where your class files reside. In the production version of the registry file, it should identify your JAR files. The JAR file names should not be qualified with any directory names - iSeries Navigator will qualify them automatically when it constructs the classpath string to be passed to the Java VM.

JavaMRI: The base names of the JAR files that contain locale-dependent resources for the plug-in. iSeries Navigator will search for each JAR file after first suffixing the name with the appropriate Java language and country identifiers. In the development version of the registry file this field may contain an empty string, since the resources for the base locale (usually US English) should reside in the code JAR.

Defining new folders

;--------------------------------------------------------------------
; Register a new folder

[HKEY_CLASSES_ROOT\IBM.AS400.Network\3RD PARTY EXTENSIONS\IBM.MsgQueueSample3\folders\Sample3]
"Parent"="AS4"
"Attributes"=hex:00,01,00,a0
"CLSID"="{1827A856-9C20-11d1-96C3-00062912C9B2}"
"JavaClass"="com.ibm.as400.opnav.MsgQueueSample3.MqListManager"
"NameID"=dword:0000000b
"DescriptionID"=dword:0000000c
"DefaultIconIndex"=dword:00000001
"OpenIconIndex"=dword:00000000
"AdminItem"="QIBM_SAMPLE_SMPFLR"
"TaskpadNameID"=dword:00000003
"TaskpadDescriptionID"=dword:00000004

Type: Each new folder that your plug-in adds to the iSeries Navigator hierarchy has a unique logical type. In the example above, the string Sample3 is the type which will be used to identify the currently selected folder when control is passed to your plug-in at runtime.

Parent

A three-character ID that identifies the parent of the folder to be added. One of the following IDs may be specified:

ADF	Application Development folder
AS4	iSeries server folder
BKF	Backup folder
BOF	Basic Operations folder
CFG	Configuration and Service folder
DBF	Database folder
FSF	File Systems folder
MCN	Management Central folder
MCS	Management Central Configuration and Service folder
MDF	Management Central Definitions folder
MMN	Management Central Monitors
MST	Management Central Scheduled Tasks
MTA	Management Central Task Activity
MXS	Management Central Extreme Support
NSR	Network Servers folder
NWF	Network folder
SCF	Security folder
UGF	Users and Groups folder
WMF	Work Management folder

Attributes: A 4-byte binary field that contains the attributes for the folder, with the indicator bytes in reverse order. See the folder attribute flags defined for the IShellFolder::GetAttributesOf method in the Microsoft include file SHLOBJ.H. To indicate that your folder has a taskpad, use 0x00000008.

CLSID: The CLSID of the IA4HierarchyFolder implementation that should be called by iSeries Navigator to obtain the contents of the folder. For Java plug-ins this CLSID should always be {1827A856-9C20-11d1-96C3-00062912C9B2}.

JavaClass: The fully-qualified Java class name of the ListManager implementation that should be called by the iSeries Navigator to obtain the contents of the folder.

NameID: A double word that contains the resource ID of the string that should appear as the name of the folder in the iSeries Navigator hierarchy.

DescriptionID: A double word that contains the resource ID of the string that should appear as the description of the folder in the iSeries Navigator hierarchy.

DefaultIconIndex: A double word that contains the index into the NLS resource DLL of the plug-in for the icon that should be displayed for the folder in the iSeries Navigator hierarchy. This is a zero-based index into the resource DLL, not the resource ID of the icon. For indexing to work properly, the icon resource IDs should be assigned sequentially.

OpenIconIndex: A double word that contains the index into the NLS resource DLL of the plug-in for the icon that should be displayed for the folder in the iSeries Navigator hierarchy whenever it is selected by the user. This may be the same as the default icon index.

AdminItem: A STRING that contains the Function ID of the Application Administration function that controls access to the folder. If this field is omitted, no Application Administration function controls access to the folder. If specified, this must be the function ID of a Group or Administrable function. It cannot be the function ID of a Product Function.

TaskpadNameID: A double word that contains the resource ID of the string that should appear as the name of the taskpad in the iSeries Navigator hierarchy.

TaskpadDescriptionID: A double word that contains the resource identifier of the text string in the resource DLL. This resource DLL is used to describe the function of the taskpad in the iSeries Navigator user interface.

Adding context menu items

;--------------------------------------------------------------------
; Register a context menu handler for the new folder and its objects

[HKEY_CLASSES_ROOT\IBM.AS400.Network\3RD PARTY EXTENSIONS\IBM.MsgQueueSample3\
   shellex\Sample3\*\ContextMenuHandlers\{1827A857-9C20-11d1-96C3-00062912C9B2}]
"JavaClass"="com.ibm.as400.opnav.MsgQueueSample3.MqActionsManager"

;------------------------------------------------------------------------------
; Register a drag/drop context menu handler for the new folder and
its objects

[HKEY_CLASSES_ROOT\IBM.AS400.Network\3RD PARTY EXTENSIONS\IBM.MsgQueueSample3\
   shellex\Sample3\*\DragDropHandlers\{1827A857-9C20-11d1-96C3-00062912C9B2}]
"JavaClass"="com.ibm.as400.opnav.MsgQueueSample3.MqActionsManager"

Adding taskpad tasks

;--------------------------------------------------------------------
; Register a task handler for the new folder and its objects

[HKEY_CLASSES_ROOT\IBM.AS400.Network\3RD PARTY EXTENSIONS\IBM.MsgQueueSample5\
   shellex\Sample5\*\TaskHandlers\{1827A857-9C20-11d1-96C3-00062912C9B2}]
"JavaClass"="com.ibm.as400.opnav.MsgQueueSample5.MqTasksManager"
"JavaClassType"="TasksManager"

Supporting drag/drop

;--------------------------------------------------------------------
; Register a drop handler for the new folder and its objects

[HKEY_CLASSES_ROOT\IBM.AS400.Network\3RD PARTY EXTENSIONS\IBM.MsgQueueSample3\
    shellex\Sample3\*\DropHandler]
@="{1827A857-9C20-11d1-96C3-00062912C9B2}"
"JavaClass"="com.ibm.as400.opnav.MsgQueueSample3.MqDropTargetManager"

Specifying the objects to be managed

A pair of object type identifiers is required under the shellex key. The first identifier in the pair specifies the root folder for an iSeries Navigator component. For new folders added by your plug-in, this identifier should match the logical type of the folder you specified as your junction point. For existing folders, this subkey should generally be the object type of the first-level folder under an iSeries server container object. These type strings are defined under HKEY_CLASSES_ROOT\IBM.AS400.Network\TYPES in the registry.

The second identifier in the pair identifies the specific object type that the plug-in wants to affect. If "*" is specified, the plug-in will be called the for the folder type identified in the first identifier, plus all folders and objects which appear in the hierarchy under that folder. Otherwise, a specific type identifier should be specified, and the plug-in will only be called when the user performs an action on an object of that type.

Remember that any number of plug-ins may register their intent to add function to a given object type in the Navigator hierarchy. The plug-in should never assume that it is the only server component which is providing function for a given object type. This applies not only to existing object types, but also to any new objects that a plug-in may choose to define. If your plug-in is widely used, there is nothing to prevent another vendor from extending object types that are defined by your plug-in.

CLSIDs: The CLSIDs shown in the above examples specify the built-in ActiveX server component which manages Java plug-ins. For all non-folder related function this CLSID should always be {1827A857-9C20-11d1-96C3-00062912C9B2}.
JavaClass: The fully-qualified Java class name of the interface implementation that should be called by the iSeries Navigator to support the designated function.

SSL support

If a plug-in's communications with the iSeries server are performed by using the Sockets API or some other low-level communications service, then it is the responsibility of the plug-in to support SSL if it has been requested. If the plug-in doesn't provide this support, it should indicate that it doesn't support SSL as described below. When this is done, the plug-in's function will be disabled if the user has requested a secure connection.

;------------------------------------------------------------------------------
; Indicate that this plug-in supports SSL.

[HKEY_CLASSES_ROOT\IBM.AS400.Network\3RD PARTY EXTENSIONS\IBM.MsgQueueSample3\SSL]
"Support Level"=dword:00000001

Support Level: If the plug-in supports SSL, this value should be 1. Otherwise, it should be 0.