Building COM Objects

See Also

Visual J++ simplifies the building of COM objects by providing an easy-to-use interface for selecting classes in your project that you want to use as COM classes. Any public, non-abstract class can be used to create a COM object. Visual J++ uses the public members of a class as the interface to the COM object. When you build your project, classes that are selected as COM classes are built and registered in the system as COM objects. Once you have built your COM objects, you can package them in a COM DLL and access them from other programming environments or from applications that support COM.

In this scenario, you build a COM object, packaged in a COM DLL, that exposes sports-related, statistical functions. You will learn how to:

• Create a project with classes that can be exposed as COM objects.
  
  
• Use the COM Classes tab in the Project Properties dialog box to select classes in your project to expose as COM objects.
  
  
• Package the COM classes into a COM DLL for other programming languages and applications to use.
  
  
• Build the project.

Creating a Project

Visual J++ provides a COM DLL template that creates a project with a class that is already registered as a COM class. This template is also configured to package the project in a COM DLL. For more information on creating COM DLL projects using the template, see Creating a COM DLL.

Although the COM DLL template is available, this scenario does not use the template because it is important to understand how to select a class in any project as a COM class. In this scenario, you create an empty project and add a Java class to the project that will be exposed as a COM object.

Note   Before you start the following procedure, close any open projects. (On the File menu, click Close All.)

To create an empty project

1. On the File menu, click New Project.
   
   
2. In the New tab, select the Visual J++ Projects folder, and then click the Empty Project icon.
   
   
3. In the Name box, type a name for your project.

   For this scenario, type Stats.

4. In the Location box, type the path where you want to save your project, or click Browse to navigate to a directory.
   
   
5. Click Open.

   Your project appears in Project Explorer and contains no files.

To add a class to your project

1. In Project Explorer, right-click the name of your project.
   
   
2. On the shortcut menu, point to Add and then click Add Class.
   
   
3. To add an empty Java class, select the Class icon.
   
   
4. In the Name box, type a name for the Java class.

   For this scenario, name the class Stats.java.

5. Click Open.

Adding Code to the Class

For clients of your COM DLL to manipulate your COM object, you provide public methods in your COM class. Visual J++ exposes all public methods of a Java class, including those inherited from superclasses, through the interface to the COM object. For this scenario, you add two methods to the class. These methods provide sports-related statistical functions to the user of the COM object.

The first public method that the Stats COM object needs to expose is the winLossPercentage method. This method calculates the percentage of wins a team has over the total number of games that have been played by the team.

To add the winLossPercentage method

• Add the following method definition to the Stats class.

  public float winLossPercentage(int gamesPlayed, int gamesWon)
  {
     float returnValue = gamesWon % gamesPlayed * .100f;
     if (returnValue == 0.0f)
        return 1.0f;
     else
        return returnValue;
  }

This code uses the modulus operator to obtain the remainder from a division between the number of games that were won by the team and the number of games that were played. The value is then multiplied by .100f to convert the value to the type typically used in a team standings display. After the value has been determined, the code checks to see if the value is 0.0f, which indicates that there is no remainder and that the team has won all its games. If so, the code returns the value of 1.0f. Otherwise, the code returns the regular value.

The final public method that the Stats COM object needs to expose is the goalsAgainstAverage method. This method calculates the average number of goals that are allowed by a goaltender. It determines this by dividing the number of goals allowed by the goaltender by the number of complete games the goaltender has played in.

To add the goalsAgainstAverage method

• Add the following method definition to the Stats class.

  public float GoalsAgainstAverage(int gamesPlayed, int goalsAllowed)
  {
     return (float) goalsAllowed/gamesPlayed;
  }

This code divides the number of goals allowed by the number of games played and casts the result as a float value.

Defining a Class as a COM Class

After you have created your class and defined the public methods will be exposed through COM, you define the class as a COM class. Use the COM Classes tab in the Project Properties dialog box to select classes from your project as COM classes.

Note   If you do not need to define multiple classes as COM classes, you can define a COM class in the Class Properties dialog box. To display the Class Properties dialog box, in Class Outline, right-click the name of the class, and then click Class Properties. In the Class Properties dialog box, select the COM Class check box.

To define a class as a COM Class

1. On the Project menu, click <Project> Properties (where <Project> is the name of your control project).
   
   
2. Click the COM Classes tab.
   
   
3. In the COM Classes tab, select the Automatically generate Type Library option.
   
   
4. In the list of classes, select the name of the class that you want to expose as a COM object.

   For this scenario, select the Stats class.

5. Click OK.

   Visual J++ adds an @com.register comment tag to the top of your class definition. When your project is compiled, the compiler uses the information in the comment tag to register your class as a COM class in the registry.

Packaging the Project as a COM DLL

So that other applications can access your COM object, you package it in a COM DLL.

Note   If you want to distribute your COM object over the Internet, you can package your control in a CAB file instead of a COM DLL.

To package your COM object in a COM DLL

1. On the Project menu, click <Project> Properties (where <Project> is the name of your control project).
   
   
2. Click the Output Format tab.
   
   
3. Select the Enable Packaging check box.
   
   
4. In the Packaging type drop-down list, select COM DLL.
   
   
5. In the File name box, type a name for your COM DLL. (A default name is created for you using the name of the project.)
   
   
6. Select the Outputs of type and the Java Classes & Resources options.
   
   
7. Click OK.

Building the Project

During the build process, Visual J++ packages your COM classes in a COM DLL and registers the DLL and the COM classes within it as COM objects. When the classes are in the registry, they are available to other applications. For more information on importing a COM object into Visual J++, see Importing COM Objects.

To build your project

• On the Build menu, click Build. (If you receive any compilation errors or message, correct the errors and rebuild your project.)

Note   To perform additional registration while your COM class is being registered, you can add a user-defined method named onCOMRegister to your COM class. You can use this method to perform tasks such as registering a Visual J++ add-in into the list of Visual J++ add-ins. This method is called by Visual J++ during the COM registration process for COM classes and during the registration of a COM DLL built with Visual J++. The signature of the onCOMRegister method must match the following signature:

public static void onCOMRegister(boolean register)
{
   // Add your custom registration code here
}