The heart of the Tweek software system implements the Observer pattern [Gam95]. This design pattern is used to define the relationship between the Java GUI (observer) and the C++ application (subject). Within this section, we explain how the subject and observer are used. Moving beyond the subject/observer pattern, we also explain the Subject Manager and the CORBA Manager. These four components make up the entirety of the C++ design.

CORBA, the Common Object Request Broker Architecture, is a powerful tool for distributed programming. It is a language-independent standard specified by the Object Management Group (OMG). Many CORBA implementations, both free and commercial, exist for a wide variety of languages (e.g., C, C++, Java, Perl, Python, and Smalltalk). CORBA allows communication between software written in any programming language running on any operating system on any hardware architecture. It handles all serialization and de-serialization of objects and method parameters so that programmers do not have to worry about endian issues and other system incompatibilities.

Before going further with the discussion of CORBA in Tweek, readers must be familiar with some terminology. In CORBA, the physical object to which references are made is called a servant. The servant is an instance of some class that implements an interface and derives from CORBA::Object (or org.omg.CORBA.Object in Java). The actual details of servant implementations are postponed for later sections. For now, it is important to remember that there will be an object located in physical memory on some machine, and references will be made to that object through CORBA. Users acquire references by looking up the object by name in what is known as the CORBA Naming Service. The Naming Service has objects registered within its database, and clients request references from the database. When the reference is made available, methods may be invoked on it. Since the physical object resides in another memory space, this will create network traffic, though it is entirely transparent to the programmer.

CORBA uses Object Request Brokers (ORBs) to manage locally registered objects and to communicate with remote objects. The remote objects are managed by ORBs that reside locally on the machines that have the servants. Two ORBs communicate with each other using a standard protocol. In this case, that protocol is the Internet Inter-ORB Protocol (IIOP). IIOP is a new addition to Version 2.3 of the CORBA standard. It allows two ORBs written by different vendors to communicate and inter-operate. This capability is crucial to the correct functionality of Tweek and many other CORBA-based software systems.

Within the scope of Tweek, CORBA is used to enable transparent communication between C++ applications and the Tweek Java GUI. C++ objects registered with a local ORB are made available to the Java GUI through the Subject Manager. Beyond this, CORBA exists mostly "behind the scenes" so that developers of Tweek-based software do not have to learn very much about CORBA. Programmers must understand the Interface Definition Language, however, and this is explained next.

There are four types of Beans that may be loaded by the Tweek Java GUI. They are categorized based on functionality and what is known about them in advance. The following lists the four categories in order of decreasing a priori knowledge.

All JavaBeans loaded by the Tweek Java GUI are describe by at least one XML file. The XML file can contain information about many Beans or about a single Bean. The XML file itself is a “beanlist” document. The four Bean categories, described above, each have an XML element that has children giving information about the specific Bean. The elements are <service>, <viewer>, <guipanel>, and <generic>.

All Bean XML entries must contain a <file> element. Through its source attribute, this element provides the path to the JAR file that contains the full Bean code. When specifying the JAR file path, environment variables may be used. They must use the syntax ${ENV_VAR} (the curly braces are required). The class element gives the fully qualified name of the class stored within the JAR file that will be instantiated. The extension .class must not be specified. This is to allow the use of serialized classes which have the extension .ser. The Tweek Bean-loading code will figure out what is available and take the right actions.

In addition to the <file> element, a <dependencies> element may be specified. Dependencies of the Bean may be named as external JAR files or other Beans may be listed therein. The <dependencies> element may contain zero of more elements of type <jar> and/or <bean>. The <jar> element has a single attribute, path, which gives the path (a semi-colon separated list of directories) where the JAR file may be found. The contents of the <jar> element defines the name of the JAR file. The <bean> element's contents defines the name of the Bean that the current Bean depends on.

Of the four Bean categories, the XML for Panel Beans can contain the most information. In addition to the previously mentioned elements, Panel Bean entries may have two optional elements: <tree> and <icon>. The element <tree> specifies the path within the Bean tree hierarchy where the Panel Bean will be placed. The path is given as a /-separated list of directories. If the named path does not exist when the Bean is loaded, it will be created. The element <icon> names a custom icon for the Bean and a tool-tip. An example of a Panel Bean XML entry is shown in Example 2.1, “PlexusGraphView.xml snippet”. Note that this is not the full file—it is only the <guipanel> element for a single Bean.

<guipanel name="Graph View">
  <file name="${PLX_BASE_DIR}/share/plexus/beans/PlexusGraphView.jar" 
        class="plx.graphview.GraphView" />
  <tree path="/" />
  <dependencies>
    <jar path="${PLX_BASE_DIR}/share/plexus/beans">openjgraph.jar</jar>
    <jar path="${PLX_BASE_DIR}/share/plexus/beans">jgraph.jar</jar>
    <jar path="${PLX_BASE_DIR}/share/plexus/beans">PlexusComm.jar</jar>
  </dependencies>
  <icon source="jar:file:${PLX_BASE_DIR}/share/plexus/beans/PlexusGraphView.jar!/plx/graphview/icon.gif"
        tooltip="Plexus Network Graph Visualization" />
</guipanel>

This shows the use of all the elements that may be children of <guipanel>. Note that the source attribute of <icon> gets its icon image using a JAR URL.

Another example XML file is shown in Example 2.2, “Viewers.xml”. This is the actual file used to load the two Viewer Beans that come with the Tweek distribution. This is a complete file containing two Viewer Bean entries.

<?xml version="1.0" encoding="UTF-8"?>
<beanlist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="http://www.vrjuggler.org/tweek/xsd/1.1/beanlist.xsd">
  <viewer name="Tree Viewer">
    <file name="${TWEEK_BASE_DIR}/share/tweek/beans/Viewers.jar" 
          class="org.vrjuggler.tweek.treeviewer.BeanTreeViewer" />
  </viewer>
  <viewer name="Icon Viewer">
    <file name="${TWEEK_BASE_DIR}/share/tweek/beans/Viewers.jar" 
          class="org.vrjuggler.tweek.iconviewer.BeanIconViewer" />
  </viewer>
</beanlist>

To create a custom subject implementation, you must derive from two classes: the abstract class that defines the custom interface and tweek::SubjectImpl. Referring back to the interface shown in Example 3.2, “CustomSubject.idl”, the basic C++ class declaration would appear as follows:

  1 #ifndef _CUSTOM_SUBJECT_IMPL_H_
    #define _CUSTOM_SUBJECT_IMPL_H_
    
    #include <tweek/CORBA/SubjectImpl.h>
  5 #include <CustomSubject.h>
    
    namespace mymod
    {
    
 10 class CustomSubjectImpl : public POA_mymod::CustomSubject,      
                              public tweek::SubjectImpl             
    public:
       CustomSubjectImpl() : mValue(0.0f)
       {
 15       ;
       }
    
       virtual ~CustomSubjectImpl()
       {
 20       ;
       }
    
       virtual float getValue();                                    
    
 25    virtual void setValue(float v);                              
    
       mymod::CustomSubject_ptr _this()                             
       {
          return POA_mymod::CustomSubject::_this();
 30    }
    
    private:
       float mValue;
    };
 35 
    }
    
    #endif

The implementations of getValue() and setValue() are fairly obvious, though they are presented here for the sake of completeness. Note, however, that setValue() changes the state of the subject, and thus any observers must be notified of the change. The implementations are shown in the following example.

#include <CustomSubjectImpl.h>

namespace mymod
{

float CustomSubjectImpl::getValue()
{
   return mValue;
}

void CustomSubjectImpl::setValue(float v)
{
   mValue = v;
   tweek::SubjectImpl::notify();
}

}

The key point to note is the call to tweek::SubjectImpl::notify() in the setValue() implementation. In general, anything that modifies the state of the subject requires that this method be invoked. Note also that the method is fully qualified so that we are sure to call the correct implementation.

Initializing the CORBA Manager is straightforward, but it does require exception handling. If the exceptions are not handled correctly, applications will abort if an exception is thrown but not caught. Refer to a C++ reference for more information about exceptions and exception handling in C++.

The following example shows a main() function for an application that performs all the Tweek initialization steps. We separate the discussion into two parts: one part for the CORBA Manager and one part for the Subject Manager (discussed in the next section).

  1 #include <vpr/vpr.h>
    #include <vpr/Thread/Thread.h>
    #include <vpr/Util/Debug.h>
    #include <tweek/CORBA/CorbaManager.h>                         
  5 
    #include <CustomSubjectImpl.h>                                
    
    /**
     * This application starts the CORBA server for the C++ side
 10  * of the test.
     */
    int main(int argc, char* argv[])
    {
       tweek::CorbaManager mgr;                                   
 15 
       // The first thing we have to do is initialize the Tweek
       // CORBA Manager.  If this fails, we're out of luck.
       try                                                        
       {
 20       if ( mgr.init("example", argc, argv) )                  
          {
             bool status(false);
    
             // Once the CORBA Manager is initialized, we need
 25          // to create a Subject Manager.  This will hold our
             // CustomSubject object.
             try
             {
                status = mgr.createSubjectManager();
 30 
                // If we were able to create the Subject Manager,
                // now we register our objects with it.
                if ( status )
                {
 35                // First, create real instances of the C++
                   // object that will be the CORBA servant.  This
                   // must be allocated on the heap.
                   mymod::CustomubjectImpl* custom_subj =
                      new mymod::CustomSubjectImpl();
 40 
                   // Now we try to register the subject and give
                   // it a symbolic, easy-to-remember name.
                   try
                   {
 45                   mgr.getSubjectManager()->
                         registerSubject(slider_subj, "CustomSubject");
                   }
                   catch (...)
                   {
 50                   vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
                         << "Failed to register subject\n"
                         << vprDEBUG_FLUSH;
                   }
    
 55                // We are done with our pointer to the servant.
                   slider_subj->_remove_ref();
                }
             }
             catch (CORBA::Exception& ex)
 60          {
                vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
                   << "Caught an unknown CORBA exception when "
                   << "trying to register!\n" << vprDEBUG_FLUSH;
             }
 65 
             if ( ! status )
             {
                vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
                   << "Failed to register Subject Manager instance\n"
 70                << vprDEBUG_FLUSH;
             }
    
             std::cout << "Press 'x' to exit" << std::endl;
             char input;
 75 
             // Loop forever so that we can act sort of like
             // a server.
             while ( 1 )
             {
 80             std::cin >> input;
                if ( input == 'x' )
                {
                   break;
                }
 85             else
                {
                   vpr::System::msleep(100);
                }
             }
 90       }
          else
          {
             vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
                << "CORBA failed to initialize\n"
 95             << vprDEBUG_FLUSH;
          }
       }
       catch (...)                                               
       {
100       vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
             << "Caught an unknown exception!\n"
             << vprDEBUG_FLUSH;
       }
    
105    vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
          << "Exiting\n" << vprDEBUG_FLUSH;
    
       return 0;
    }

To demonstrate use of the Subject Manager, we begin by revisiting the main() function examined in the previous section. This time, we will focus our attention on the code related to the Subject Manager only. We will also explain how to use the extended API of the Subject Manager implementation.

It is important to know that the Subject Manager is a CORBA object that can be accessed by remote code. In the following example, the methods used are defined in the class tweek::SubjectManagerImpl, the C++ implementation of the tweek::SubjectManager interface. The details of how the Subject Manager is handled through CORBA are largely irrelevant for most users of Tweek. Simply bear in mind that the Subject Manager is accessibly remotely and that it simplifies the use of CORBA in general.

  1 #include <vpr/vpr.h>
    #include <vpr/Thread/Thread.h>
    #include <vpr/Util/Debug.h>
    #include <tweek/CORBA/CorbaManager.h>
  5 
    #include <CustomSubjectImpl.h>
    
    /**
     * This application starts the CORBA server for the C++ side of
 10  * the test.
     */
    int main(int argc, char* argv[])
    {
       tweek::CorbaManager mgr;
 15 
       // The first thing we have to do is initialize the Tweek
       // CORBA Manager.  If this fails, we're out of luck.
       try
       {
 20       if ( mgr.init("corba_test", argc, argv) )
          {
             bool status(false);
    
             // Once the CORBA Manager is initialized, we need to
 25          // create a Subject Manager.  This will hold our
             // CustomSubject object.
             try
             {
                status = mgr.createSubjectManager();              
 30 
                // If we were able to create the Subject Manager,
                // now we register our objects with it.
                if ( status )
                {
 35                // First, create real instances of the C++
                   // object that will be the CORBA servant.  This
                   // must be allocated on the heap.
                   mymod::CustomubjectImpl* custom_subj =
                      new mymod::CustomSubjectImpl();             
 40 
                   // Now we try to register the subject and give
                   // it a symbolic, easy-to-remember name.
                   try
                   {
 45                   mgr.getSubjectManager()->
                         registerSubject(custom_subj,
                                         "CustomSubject");        
                   }
                   catch (...)
 50                {
                      vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
                         << "Failed to register subject\n"
                         << vprDEBUG_FLUSH;
                   }
 55 
                   // We are done with our pointer to the servant.
                   custom_subj->_remove_ref();
                }
             }
 60          catch (CORBA::Exception& ex)
             {
                vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
                   << "Caught an unknown CORBA exception when "
                   << "trying to register!\n"
 65                << vprDEBUG_FLUSH;
             }
    
             if ( ! status )
             {
 70             vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
                   << "Failed to register Subject Manager instance\n"
                   << vprDEBUG_FLUSH;
             }
    
 75          std::cout << "Press 'x' to exit" << std::endl;
             char input;
    
             // Loop forever so that we can act sort of like
             // a server.
 80          while ( 1 )                                          
             {
                std::cin >> input;
                if ( input == 'x' )
                {
 85                break;
                }
                else
                {
                   vpr::System::msleep(100);
 90             }
             }
          }
          else
          {
 95          vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
                << "CORBA failed to initialize\n" << vprDEBUG_FLUSH;
          }
       }
       catch (...)
100    {
          vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
             << "Caught an unknown exception!\n" << vprDEBUG_FLUSH;
       }
    
105    vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
          << "Exiting\n" << vprDEBUG_FLUSH;
    
       return 0;
    }

The GUI Library contains the heart of the Tweek Java GUI. Indeed, this library is what contains the Tweek Java GUI, and it makes use of all the other Tweek Java libraries to do its job. In general, there is not much code in this library that is of interest to Bean developers. The lone exception is the singleton org.vrjuggler.tweek.gui.MessagePanel. This class provides access to the message panel at the bottom of the Tweek Java GUI layout. Tweek Bean authors can make use of this singleton to post messages to that panel for users of the Tweek GUI to see. In most cases, this should be the preferred method of printing status messages rather than using System.out.print*() or System.err.print*() simply because users of the GUI may not have easy access to the console to see the messages printed there. The GUI Library is found in $TWEEK_BASE_DIR/share/tweek/java/Tweek.jar.

The Bean Library is provided to help simplify the process of loading and managing JavaBeans. The internal handling of JavaBeans performed by the Tweek Java GUI uses classes in this library to communicate with other objects when Beans are loaded, instantiated, removed, etc. The Bean Library is found in $TWEEK_BASE_DIR/share/tweek/java/TweekBeans.jar.

The Event Library is used by the GUI Library (i.e., by the Tweek Java GUI) to inform Panel Beans about GUI events. This includes events such as GUI iconification, GUI closing, and the gaining and losing of focus by the GUI. The Event Library is found in $TWEEK_BASE_DIR/share/tweek/java/TweekEvents.jar.

An interesting part of the Event Library is the Event Listener Registry. Historically, the Tweek Java GUI has performed automatic, run-time registration of Beans as event listeners based on the interface(s) that the Beans implement. That is not always convenient, however. For example, a Panel Bean author may want to use utility classes as event listeners rather than the Panel Bean itself. In this case, the utility classes can be registered manually with the Tweek Java GUI using the Event Listener Registry.

The Network Library abstracts the use of CORBA by the Tweek Java GUI^[2]. It includes the CORBA Service class that handles all ORB and remote reference management, and it has all the Java classes generated by the IDL-to-Java compiler when the Tweek Java API was compiled. Beyond this, it includes the event listener interface for Tweek Beans that wish to be notified of network connection and disconnection events. The Network Library is found in $TWEEK_BASE_DIR/share/tweek/java/TweekNet.jar.

The Bean Delivery Library makes use of the Bean Library and the Network Library to allow JavaBeans to be transferred across the network. More specifically, a remote subject, most likely written in C++, can “push” JavaBeans to the Tweek GUI where they can be handled as though they were loaded from the local disk. The Bean Delivery Library is found in $TWEEK_BASE_DIR/share/tweek/java/TweekEventDelivery.jar.

In this example, we explain how to develop a simple Tweek interface. The goal is to have a “collaborative” slider in a Java GUI component. The value displayed by the slider is retained by a C++ application so that multiple independent sliders can show the same value. The steps explained here are highly representative of the normal steps to be followed when using the Tweek Java and C++ APIs. The structure of the following sections lays out the order of the steps taken. An example makefile that goes along with the code presented can be found in the section called “SliderSubject” of Appendix A, Compiling Example Code. The full source for the examples presented in this section can be found in $TWEEK_BASE_DIR/share/test/NetworkTestBean.

  1 #ifndef _NETWORK_TEST_SLIDER_SUBJECT_IDL_    
    #define _NETWORK_TEST_SLIDER_SUBJECT_IDL_    
    
    #include <tweek/idl/Subject.idl>             
  5 
    module networktest                           
    {
       interface SliderSubject : tweek::Subject  
       {
 10       void setValue(in long val);            
          long getValue();                       
       };
    };
    
 15 #endif                                       
    

  1 #ifndef _SLIDER_SUBJECT_IMPL_H_
    #define _SLIDER_SUBJECT_IMPL_H_
    
    #include <tweek/tweekConfig.h>
  5 
    #include <vector>
    
    #include <tweek/CORBA/SubjectImpl.h>                           
    #include <SliderSubject.h>                                     
 10 
    namespace networktest                                          
    {
    
    /**
 15  * This class is an extension to the base Tweek SubjectImpl class.
     * It uses multiple inheritance with that class and with the
     * generated CORBA class corresponding to the IDL for
     * SliderSubject.
     */
 20 class SliderSubjectImpl
        : public POA_networktest::SliderSubject                    
        , public tweek::SubjectImpl
    {
    public:
 25    SliderSubjectImpl()
          : tweek::SubjectImpl(), mValue(0)
       {
          /* Do nothing. */ ;
       }
 30 
       virtual ~SliderSubjectImpl()
       {
          /* Do nothing. */ ;
       }
 35 
       /**
        * Sets this subject's internal value.
        */
       virtual void setValue(long value);                          
 40 
       /**
        * Returns this subject's internal value.
        */
       virtual long getValue();                                    
 45 
       /**
        * This overriding method is needed so that the correct type
        * is returned when the _this() method is invoked.  Without
        * this method, an object of type tweek::Subject_ptr would
 50     * be returned.
        *
        * XXX: It may be possible to remove this requirement in
        * the future.
        */  
 55    networktest::SliderSubject_ptr _this()                      
       {
          return POA_networktest::SliderSubject::_this();
       }
    
 60 private:
       long mValue;   /**< Our value */                            
    };
    
    } // End of networktest namespace
 65 
    
    #endif /* _SLIDER_SUBJECT_IMPL_H_ */

  1 #include <vpr/Util/Debug.h>
    #include <SliderSubjectImpl.h>                   
    
    namespace networktest
  5 {
    
    void SliderSubjectImpl::setValue(long value)
    {
       mValue = value;                               
 10 
       // Notify any observers that our value has changed.  This is very
       // important.
       tweek::SubjectImpl::notify();                 
    }
 15 
    long SliderSubjectImpl::getValue()
    {
       return mValue;                                
    }
 20 
    } // End networktest namespace