Registration in a Separate Registration Class

The preferred way to register a snap-in is to implement the Registration interface in a separate registration class, separate from your snap-in class, to contain the registration information for your snap-in. This registration class can contain the registration information for multiple snap-ins, eliminating the need to implement the getRegistration() method within each individual snap-in class that you create. This registration technique is more efficient at startup time than implementing the Registration interface in each snap-in class. The following code example creates a registration class that will register four different snap-ins (ExamplePage, ExampleStatusBar, ExampleMenu and ExampleToolBar) all within the Example namespace.

 public class MyRegistrar implements Registration
  {
     public RegistrationItem[] getRegistration()
     {
        RegistrationItem[] ri = new RegistrationItem[4];
        ri[0] = new RegistrationItem(new NamespaceScope(Shell.SNAPIN_PAGE, "Example"), "com.example.snapins.ExamplePage");
        ri[1] = new RegistrationItem(new NamespaceScope(Shell.SNAPIN_STATUSBARITEM, "Example"), "com.example.snapins.ExampleStatusBar");
        ri[2] = new RegistrationItem(new NamespaceScope(Shell.SNAPIN_MENU, "Example"), "com.example.snapins.ExampleMenu");
        ri[3] = new RegistrationItem(new NamespaceScope(Shell.SNAPIN_TOOLBARITEM, "Example"), "com.example.snapins.ExampleToolBar");
        return ri;
     }
  }
 

Registration Using a Manifest File

The ConsoleOne shell registers each snap-in in a collection by loading each class file in the collection. The shell checks to see if each class file implements the Registration interface, and if so, calls the getRegistration() method. To speed up registration by preventing every class in a large collection from being checked, you can include a manifest file in the collection that identifies which classes are registration classes. This might be done particularly when many classes in a large collection are supporting classes.

Snap-in classes are packaged into JAR collection files and placed in the Snapins directory relative to where ConsoleOne is installed. At startup, the ConsoleOne shell then registers all of the snap-ins in such JAR collections by loading each class file in the collection which implements the Registration interface. In a process called introspection, the shell checks each class found in the JAR file to see if it implements the Registration interface, and if so, calls its getRegistration() method.

To prevent every class in a large snap-in collection from being checked, you can include a manifest file in the JAR file that identifies which classes implement the Registration interface. This should be done when many of the classes in a large collection are merely "supporting classes" since ConsoleOne can quickly load the appropriate registration classes without introspecting all the classes in the JAR.

The JAR collection file contains identification information which is provided in the header section of the manifest file. The information that the shell is looking for includes

Each class listed in the manifest file that includes the tag "Snapin-Registrar:True" will be registered by ConsoleOne. All other classes will be ignored.

For example, suppose company "Xyz Corp. developed two snap-ins (ExampleFileNamespace and ExampleFileNamespaceDisplay) within a directory structure under "com/xyz/snapin". A manifest file for these snap-ins might look like this:

 Manifest-Version: 1.0
 Snapin-Collection-Name: Example File Manager
 Snapin-Collection-Description: File System Manager Snapin
 Snapin-Collection-Copyright: (c) Xyz Corp., 1997. All rights reserved.
 Specification-Version: 1.2
 Implementation-Version: 1.5
 Snapin-Collection-AutoRegister: False
 
 Name: com.xyz.snapin.ExampleFileNamespace.class
 Snapin-Registrar: True
 
 Name: com.xyz.snapin.ExampleFileNamespaceDisplay.class
 Snapin-Registrar: True
 

The manifest file and the accompanying class files should be added to a JAR file, which should be placed in the ConsoleOne snapins directory. The snap-ins will be registered during the ConsoleOne startup as described above.

getSnapinName()

The getSnapinName() method allows the shell to provide a descriptive, localized name (translated string object) for your snap-in. You should implement this method to return a name for the selected snap-in. The getSnapinName() method will be called before the initSnapin() method. The getSnapinName() method can be implemented as follows:

 public String getSnapinName()
 {
    return "Snap-in Name";
 }
 

getSnapinDescription()

The getSnapinDescription() method allows the shell to provide the localized description (translated string object) of your snap-in. You should implement this method to return a description for the selected snap-in. The description should be kept brief and concise. The getSnapinDescription() method will be called before the initSnapin() method. The getSnapinDescription() method is implemented as follows:

 public String getSnapinDescription()
 {
    return "Snap-in Description";
 }
 

initSnapin(info)

The initSnapin() method is called by the shell to allow the snap-in to be initialized. The getSnapinName() and getSnapinDescription() methods will be called before initSnapin(). The initSnapin() method allows the snap-in to perform any necessary initialization and to pass references to the InitSnapinInfo class. Examples of this initialization might be to add itself as an event listener or read data from a data store. The initSnapin() method is implemented as follows:

 public boolean initSnapin(InitSnapinInfo info)
 {
    shell = info.getShell();
    type = info.getSnapinType();
    context = info.getSnapinContext();
    .
    .   /*Initialize snap-in; return true if successful,
    .     otherwise return false.*/
    .
    return true;
 }
 

The snap-in should return true if it is able to successfully complete initialization, or if initialization fails, false is returned and the specific instance of the snap-in will be disabled. The initSnapin() method has a single parameter, info, which contains data the snap-in can use, such as a reference to the shell, a reference to the snap-in type, and can contain a reference to snap-in context data. This information is defined in two associated classes.

 shell = info.getShell()
 

 type = info.getSnapinType()
 

 context = info.getSnapinContext()
 

shutdownSnapin()

The shutdownSnapin() method is called by the shell when the snap-in is being shut down. This method is called by the shell for each snap-in when it is no longer required. This allows the snap-in to perform any necessary cleanup, such as removing itself as an event listener. The shutdownSnapin() method is implemented as follows:

 public void shutdownSnapin()
 {
    .
    .   /*Shut down listeners, etc.*/
    .
 }