Websphere MQ Everyplace

com.ibm.mqe.registry
Class MQePrivateRegistryConfigure

java.lang.Object
  |
  +--com.ibm.mqe.registry.MQePrivateRegistryConfigure

public class MQePrivateRegistryConfigure
extends java.lang.Object

This class is used to configure a Private Registry. The class is used to get new credentials (private and public certificates) for the registry.

This class is a descendant of MQeRegistry.


Constructor Summary
MQePrivateRegistryConfigure()
          This is an empty constructor that is designed for dynamic loading and must be followed by a call to activate(java.lang.String, com.ibm.mqe.MQeFields, java.lang.String).
MQePrivateRegistryConfigure(java.lang.String name, MQeFields regParams, java.lang.String pin)
          This constructor saves the name and opens the registry; it is equivalent to the empty constructor followed by a call to activate(java.lang.String, com.ibm.mqe.MQeFields, java.lang.String).
 
Method Summary
 void activate(java.lang.String name, MQeFields regParams, java.lang.String pin)
          Initializes the class and opens the registry.
 void close()
          Closes the registry and tidies up.
 boolean credentialsExist()
          Checks whether credentials already exist for the registry.
 void getCredentials(MQeFields regParams, java.lang.String regPIN, java.lang.String miniCertServer, java.lang.String miniCertPIN, java.lang.String renamePrefix)
          Obtains new credentials for the registry.
 boolean isPrivateRegistry()
          Checks whether the registry is a private registry.
 void renewCertificates(java.lang.String regPIN, java.lang.String miniCertServer, java.lang.String miniCertPIN, java.lang.String renamePrefix)
          Renews the public certificate for the registry.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MQePrivateRegistryConfigure

public MQePrivateRegistryConfigure()

This is an empty constructor that is designed for dynamic loading and must be followed by a call to activate(java.lang.String, com.ibm.mqe.MQeFields, java.lang.String).


MQePrivateRegistryConfigure

public MQePrivateRegistryConfigure(java.lang.String name,
                                   MQeFields regParams,
                                   java.lang.String pin)
                            throws java.lang.Exception

This constructor saves the name and opens the registry; it is equivalent to the empty constructor followed by a call to activate(java.lang.String, com.ibm.mqe.MQeFields, java.lang.String).

Parameters:
name - The name associated with this registry.
regParams - An MQeFields object containing the initialization parameters for the registry:
pin - The PIN required to open the registry. If this is null, the PIN is taken from the regParams parameter.
Throws:
java.lang.Exception - Thrown if there is a problem opening the registry.
Example:
 MQePrivateRegistryConfigure regConfig1;
 
 regConfig1 = new MQePrivateRegistryConfigure();
 try {
     MQePrivateRegistryConfigure regConfig2;
     MQeFields parms = new MQeFields();
 
     parms.putAscii(MQeRegistry.DirName, "Registry_Dir");
 
     regConfig2 = new MQePrivateRegistryConfigure("Reg2", parms, null);
 } catch (Exception e) {// Handle the exception here.
 }
 
 
Method Detail

activate

public void activate(java.lang.String name,
                     MQeFields regParams,
                     java.lang.String pin)
              throws java.lang.Exception

Initializes the class and opens the registry. This saves the registry name and opens the registry. If the regPIN parameter is not null it is used to open the registry, otherwise the registry's PIN is obtained from the regParams parameter.

Parameters:
name - The registry name.
regParams - An MQeFields object containing the initialization parameters for the registry:
  • MQeRegistry.LocalRegType (ascii): This determines the type of the registry being opened. Because this should be a private registry, this parameter should be set to com.ibm.mqe.registry.MQePrivateSession, or an equivalent alias.
  • MQeRegistry.DirName (ascii): The name of the directory holding the registry files.
  • MQeRegistry.PIN (ascii): The PIN for the private registry. This is used if the regPIN parameter on activate(java.lang.String, com.ibm.mqe.MQeFields, java.lang.String) is null.
  • MQeRegistry.KeyRingPassword (ascii): The password or passphrase used to protect the registry’s private key.
  • MQeRegistry.Separator (ascii): The character to be used as a separator between the components of an entry name. For example, . This is specified as a string but it should contain a single character, if it contains more than one only the first character is used. The same separator character should be used every time a registry is opened, it should not be changed once a registry is in use and contains entries. If this value is not specified it defaults to "+".
pin - The PIN required to open the registry. If this is null, the PIN is taken from the regParams parameter.
Returns:
void
Throws:
MQeException - Is thrown if there is a problem opening the registry.
java.lang.Exception - Is thrown if there are any other problems.
See Also:
MQeLocalSecure
Example:
 try {
     MQePrivateRegistryConfigure regConfig;
     MQeFields parms = new MQeFields();
 
     parms.putAscii(MQeRegistry.DirName, "Registry_Dir");
 
     regConfig = new MQePrivateRegistryConfigure();
     regConfig.activate("Reg", parms, null);
 } catch (Exception e) {// handle the exception here
 }
 
 

isPrivateRegistry

public boolean isPrivateRegistry()
                          throws MQeException

Checks whether the registry is a private registry.

This method checks whether the registry that has been opened is a private registry.

Returns:
'true' if this is a private registry, 'false' if not.
Throws:
MQeException - Is thrown if the class has not been activated (ie. if the registry is not open)
Example:
 try {
     MQePrivateRegistryConfigure regConfig;
     MQeFields parms = new MQeFields();
 
     parms.putAscii(MQeRegistry.DirName, "Registry_Dir");
 
     regConfig = new MQePrivateRegistryConfigure("Reg", parms, null);
     if (regConfig.isPrivateRegistry()) {//
     }
 
 } catch (Exception e) {// handle the exception here
 }
 
 

credentialsExist

public boolean credentialsExist()
                         throws MQeException

Checks whether credentials already exist for the registry.

This method checks whether the registry already contains credentials.

Returns:
'true' if credentials already exist, 'false' if not
Throws:
MQeException - Is thrown if the class has not been activated (ie. if the registry is not open).
Example:
 try {
     MQePrivateRegistryConfigure regConfig;
     MQeFields parms = new MQeFields();
 
     parms.putAscii(MQeRegistry.DirName, "Registry_Dir");
 
     regConfig = new MQePrivateRegistryConfigure("Reg", parms, null);
     if (regConfig.credentialsExist()) {//
     }
 } catch (Exception e) {// handle the exception here.
 }
 
 

getCredentials

public void getCredentials(MQeFields regParams,
                           java.lang.String regPIN,
                           java.lang.String miniCertServer,
                           java.lang.String miniCertPIN,
                           java.lang.String renamePrefix)
                    throws java.lang.Exception

Obtains new credentials for the registry.

If the registry already contains credentials, they are renamed using the renamePrefix. If the rename fails, for example, because the new name already exists in the registry, an exception is thrown and new credentials are not obtained. If an error occurs after the credentials have been renamed, they are changed back to their original names before getCredentials() returns.

This method calls the mini-certificate server and can take some time to complete.

Parameters:
regParams - An MQeFields object containing the initialization parameters for the registry:
  • MQeRegistry.LocalRegType (ascii): This determines the type of the registry being opened. Because this should be a private registry, this parameter should be set to com.ibm.mqe.registry.MQePrivateSession, or an equivalent alias.
  • MQeRegistry.DirName (ascii): The name of the directory holding the registry files.
  • MQeRegistry.PIN (ascii): The PIN for the private registry. This is used if the regPIN parameter on activate(java.lang.String, com.ibm.mqe.MQeFields, java.lang.String) is null.
  • MQeRegistry.KeyRingPassword (ascii): The password or passphrase used to protect the registry’s private key.
  • MQeRegistry.Separator (ascii): The character to be used as a separator between the components of an entry name. For example, . This is specified as a string but it should contain a single character, if it contains more than one only the first character is used. The same separator character should be used every time a registry is opened, it should not be changed once a registry is in use and contains entries. If this value is not specified it defaults to "+".
regPIN - The PIN required to open the registry. If this is null, the PIN is taken from the regParams parameter.
miniCertServer - The TCP address and port number of a mini-certificate Server.
miniCertPIN - The Certificate Request Number pre-allocated by the mini-certificate administrator to allow te registry to obtain its credentials.
renamePrefix - The prefix used to rename existing credentials, if there are any.
Returns:
void
Throws:
MQeException - Is thrown if the class has not been activated, if it is not a Private Registry, if the rename fails, or if there is an error obtaining the credentials (e.g. contacting the issuing mini-certificate server).
java.lang.Exception - Is thrown for other errors.
Example:
 try {
     MQePrivateRegistryConfigure regConfig;
     MQeFields parms = new MQeFields();
 
     parms.putAscii(MQeRegistry.DirName, "Registry_Dir");
 
     regConfig = new MQePrivateRegistryConfigure("Reg", parms, null);
     if (regConfig.isPrivateRegistry()) {
         String renamePref = Long.toString(new Date().getTime()) + "_";
 
         regConfig.getCredentials(parms,
             "MYpin 123",
             "certServer.hursley.ibm.com:8082",
             "12345678",
             renamePref);
     }
 } catch (Exception e) {// handle the exception here
 }
 
 

renewCertificates

public void renewCertificates(java.lang.String regPIN,
                              java.lang.String miniCertServer,
                              java.lang.String miniCertPIN,
                              java.lang.String renamePrefix)
                       throws java.lang.Exception

Renews the public certificate for the registry.

This method renews the public certificate for the registry. This is necessary if, for example, the existing certificate has expired.

The existing public certificate is renamed using the renamePrefix. If the rename fails, for example because the new name already exists in the registry, an exception is thrown and the certificate is not renewed. If an error occurs after the certificate has been renamed, it is changed back to its original name before renewCertificates() returns.

This method calls the mini-certificate server and can take some time to complete.

Parameters:
regPIN - The PIN required to open the registry,
miniCertServer - The TCP address and port number of the mini-certificate Server.
miniCertPIN - The Certificate Request Number pre-allocated by the mini-certificate administrator to allow te registry to renew its certificate
renamePrefix - The prefix used to rename the existing certificate.
Returns:
void
Throws:
MQeException - Is thrown if the class has not been activated, if it is not a Private Registry, if the rename fails, or if there is an error renewing the certificate (e.g. contacting the issuing mini-certificate server).
java.lang.Exception - Is thrown for other errors.
Example:
 try {
     MQePrivateRegistryConfigure regConfig;
     MQeFields parms = new MQeFields();
 
     parms.putAscii(MQeRegistry.DirName, "Registry_Dir");
 
     regConfig = new MQePrivateRegistryConfigure("Reg", parms, null);
     if (regConfig.isPrivateRegistry()) {
         String renamePref = Long.toString(new Date().getTime()) + "_";
 
         regConfig.renewCertificates("MYpin 123",
             "certServer.hursley.ibm.com:8082",
             "12345678",
             renamePref);
     }
 } catch (Exception e) {// handle the exception here
 }
 
 

close

public void close()

Closes the registry and tidies up.

This closes the configuration object and the associated registry. An attempt to use the object after it has been closed results in an exception.

Returns:
void
Example:
 try {
     MQePrivateRegistryConfigure regConfig;
     MQeFields parms = new MQeFields();
 
     parms.putAscii(MQeRegistry.DirName, "Registry_Dir");
 
     regConfig = new MQePrivateRegistryConfigure("Reg", parms, null);
     if (regConfig.credentialsExist()) {//
     }
     regConfig.close();
 } catch (Exception e) {// handle the exception here
 }
 
 

Websphere MQ Everyplace