The subjects in Tweek are part of the C++ applications. The communication “channels” are defined by the subjects' interfaces. An observer is attached to a subject, and whenever the state of a subject changes, it notifies all of its attached observers.

The Tweek C++ API defines the basic subject interface (tweek::Subject) that implements the subject pattern [Gam95]. Users of the Tweek C++ API derive from the base subject implementation (tweek::SubjectImpl) and extend it by adding their own interface methods. This extension is twofold. First, an interface must be defined using the Interface Definition Language (IDL). Then, the interface must be implemented in C++ code. (Refer to the section called “Interface Definition Language” for more information about IDL in Tweek.)

The observers in Tweek are (traditionally) part of the Java GUI^[1]. They observe the state of the remote subjects and can provide a visual rendering of that state.

Programmers do not define interfaces for the observers. Instead, the Tweek C++ API defines a basic observer interface called tweek::Observer. There is no “standard” observer implementation that corresponds to tweek::SubjectImpl. By design, observers must correspond directly with subjects, but there is no need to extend the basic observer interface using IDL. Observer implementations simply inherit from the basic observer class (tweek.ObserverPOA in Java or POA_tweek::Observer in C++) and implement the update() method. Other extensions can be added in the custom observer class, of course, but an implementation of update() is always required.

CORBA tends to have a high learning curve. It is a very powerful system, but that power leads to a lot of complexity. To reduce the complexity of starting and using an ORB, Tweek provides a CORBA Manager. Its primary function is to initialize a local ORB. It does this by creating the Portable Object Adapter (POA), resolving the initial reference to the Naming Service, and starting a thread for the ORB to handle requests.

Once the local ORB is initialized, the Subject Manager (discussed next) must be created. This is also done through the CORBA Manager because the Subject Manager is a CORBA object. The newly created Subject Manager will be a servant object to which CORBA references can be created.

Refer to the section called “CORBA” for more information about CORBA and its use in Tweek. For the most part, the use of CORBA is an implementation detail. Users of the Tweek C++ API must initialize the CORBA Manager, however, and it is important to understand its place in the overall system.

The Tweek Subject Manager exists to simplify the use of CORBA further. At a very high level, it acts as a simplified, specialized CORBA Naming Service. Users of Tweek register subject servants with the Subject Manager. The Subject Manager handles the CORBA registration and activation of the servants. After being registered, subjects are accessed using symbolic strings. The strings are user-defined and do not necessarily conform to any CORBA-related standard. They are, in essence, identifiers used to look up the subject within the Subject Manager's collection of known subjects.

The Interface Definition Language (IDL) is used by the CORBA standard to define the interfaces for remotely accessible objects. An IDL file looks very much like a simple C++ class declaration in a header file, though data members are not allowed in the interface. Thus, IDL is used exclusively to define the methods of the objects and external data structures that may be passed as arguments to those methods.

The interfaces alone are not sufficient to implement objects that may be handled by CORBA. A language-specific implementation must be written so that servants can be instantiated and registered with an ORB. To implement an interface, an IDL compiler must first be used to generate skeleton code for a specific language from the IDL file. Using the generated code, an implementation is then written. In Chapter 3, IDL, we explain in more detail how to use IDL to define interfaces.

As discussed above, a very powerful feature of CORBA is its language independence. As of this writing, Tweek itself includes support for C++ and Java as the primary langauges. Support for generating the stub code needed to access Tweek Subjects through Python was added in early August 2003, and a PyQt-based GUI is being written so that developers can use Python and Qt for making GUI panels instead of Java. There is no restriction, other than time and resources, that prevents the addition of support for other languages. In this section, we explain how C++, Java, and Python are used in Tweek.

Services encapsulate functionality that may be useful to other parts of the Tweek system or dynamically loaded code. The entire interface for Service Beans must be known when the code using the service is compiled. This is because the using code needs to be able to take advantage of the service. Because Service Beans may be loaded dynamically, using code must be prepared for the case when the Bean containing the service was not found. In other words, code that uses services cannot necessarily assume that the service will be available.

Not all services are loaded dynamically as Beans. Some services are loaded statically because they are needed by core components. These include the Environment Service and the Global Preferences Service. There is a guarantee that the code for these services will always be available. This guarantee is especially important because the Tweek core needs to add information to the Environment Service at startup. The Global Preferences Service is needed to configure the overall behavior of the Tweek GUI.

Viewer Beans provide a rendering of the tree of Panel Beans (discussed next). They provide the viewer component of the model/view pattern [Gam95]. All Viewer Beans are loaded dynamically, and the active viewer can be changed at runtime by editing the global preferences. This feature is realized through the flexibility of the model/view pattern.

Viewer Beans must implement the org.vrjuggler.tweek.beans.BeanModelViewer interface. To simplify implementation, they may be derived from org.vrjuggler.tweek.beans.DefaultBeanModelViewer, a class that implements aspects of the interface that are unlikely to vary between viewer implementations. The use of the interface is needed so that the GUI frame can assume certain behaviors about the viewer.

Most programmers using Tweek will write Panel Beans. These provide custom interfaces for whatever users need. In most cases, a Panel Bean will provide a graphical interface that can manipulate and/or control a C++ application, but developers are not strictly limited to this use.

Only one assumption is made about Panel Beans: the primary class for the Bean must be a subclass of javax.swing.JComponent. Optionally, the primary class may implement one or more publicly provided interfaces that provide the Java GUI with more information about the capabilities of the Bean. When loaded, the GUI checks to see what, if any, interfaces are implemented by the Bean. Based on the results, special actions may be taken to provide the Bean with extended functionality.

For example, Beans that can load files should implement org.vrjuggler.tweek.beans.FileLoader. When the Bean is focused in the viewer, the File menu will be modified to enable the Open, Save, and Close items. If the user selects one of these items, the Bean is informed and can take appropriate customized actions. The result in this case is context-specific loading and unloading of files.

Nothing at all is assumed about Generic Beans. This Bean category is provided so that other Beans can do their own dynamic code loading. For example, a Bean that uses a factory pattern may want to have the “workers” loaded dynamically based on some criteria. Thus, the functionality of the factory can be changed dynamically.

The Tweek Java GUI does not use Generic Beans itself. These are provided more for users of the Tweek Java API. It is up to those programmers to decide how to handle the Generic Beans on a case-by-case basis.

In order to use the Tweek Subject Manager, it must be initialized. Each CORBA Manager should have a single Subject Manager associated with it. If not, use of Tweek will be much more difficult because the CORBA Manager and the Subject Manager together hide most of the details relating to the use of CORBA. The following example shows how to initialize the Subject Manager using the CORBA Manager object created earlier.

Example 4.4. TweekApp.cpp

  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).success() )
          {
             vpr::ReturnStatus status;
    
             // 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.success() )
                {
 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.success() )
             {
 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;
    }

	After the COBRA Manager has been initialized successfully, the Tweek Subject Manager must be created. We do this by invoking the method tweek::CorbaManager::createSubjectManager() on our tweek::CorbaManager instance.
	Once we have a valid Subject Manager, we must register subjects with it in order for object references to be passed out by CORBA. This creates the servant to which mymod::CustomSubject references will be made.
	Once the servant is created, it is registered with the Subject Manager. The Subject Manager will activate the servant within the POA so that references to it can be created and returned to clients. We register it with the symbolic name “CustomSubject” that can be referenced later by remote objects.
	After the subject is registered, all the work is done. This simple application now just waits for clients to request references. It will exit when the user enters 'x'.

Note that all the code relating to the Subject Manager is enclosed within another try/catch block. This block only catches exceptions of type CORBA::Exception. Anything more general is caught by the larger try/catch block.

The class tweek::SubjectManagerImpl has some methods that are not part of the IDL-specified interface. One such method is registerSubject(), which was used in the preceding example. Some other methods that may be of interest to users are described in the following subsections.

To begin, the subject interface must be defined in IDL and implemented in C++. The interface itself will be “compiled” into Java and C++ code. Both ends of the communication channels must know the interface in order for the references to be used, thus requiring the generation of code for both languages.

Creating the Interface

Creating an IDL interface involves writing an IDL file. For this example, we will be storing an integer variable in a C++ servant. The Java GUIs will need to read and write the value, so we need two methods: getValue() and setValue(). The type being passed between ORBs will be long, a 32-bit integer. Depending on the target language, this will map to the corresponding type of the same size.

Example 6.1. SliderSubject.idl

  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                                       
    

	IDL files are run through the C preprocessor so that they may include external files. To prevent including the same source multiple times, the file must be enclosed in the traditional preprocessor protection block. This is exactly what is done in C/C++ header files.
	All Tweek subject IDL files must include tweek/idl/Subject.idl. This is required so that the interface being defined can inherit from tweek::Subject.
	Typically, using a module to contain the interface is recommended. Using a module defines a Java package and a C++ namespace (named networktest in this case).
	The definition of the subject interface must inherit from tweek::Subject. If this is not done, there is no way that the subject interface will plug into the Subject Manager.
	This simple interface has only two functions: setValue() and getValue(). The method getValue() takes a single read-only parameter of type long; getValue() returns a value of the same type.

The file SliderSubject.idl must be “compiled” by an IDL compiler. For use with Tweek, the interface must be compiled into Java and C++ code. The generated Java code will be used solely for communicating with CORBA networktest.SliderSubject references. The generated C++ code will be extended to provide an implementation of the networktest::SliderSubject interface. (The implementation will be a CORBA servant object to which references will be made by remote Java code.)

Implementing the Interface in C++

After running an IDL compiler to generate the stub CORBA code, the interface must be implemented. In particular, there will be pure virtual methods in SliderSubject.h that must be implemented. The implementing class will be the CORBA servant holding the actual data visualized in the Java GUI slider.

Example 6.2. SliderSubjectImpl.h

  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_ */

	These files will always be included by implementations of Tweek subject derived classes. The first contains the declaration for the basic Tweek subject implementation. The second contains the C++ code generated from the Tweek Observer.idl file.
	This header is generated by the IDL compiler from SliderSubject.idl. In particular, it defines the class from which networktest::SliderSubjectImpl must inherit.
	In SliderSubject.idl, shown in Example 6.1, “SliderSubject.idl”, the interface is in the networktest module. In the C++ implementation code, the module name corresponds to a namespace.
	The interface implementation class must inherit from the IDL-generated class POA_networktest::SliderSubject and from tweek::SubjectImpl.
	POA_networktest::SliderSubject defines two pure virtual methods that must be implemented. These correspond to the methods in SliderSubject.idl.
	As of this writing, all subject implementations must contain an overriding version of the _this() method. This is due to the use of multiple inheritance. Note the return type and the return statement. These will vary for each subject implementation based on the name of the IDL-defined interface.
	This is the actual value being stored by the C++ servant.

In SliderSubjectImpl.h, the most important parts to note are the use of multiple inheritance, the declarations of the SliderSubject interface methods, and the implementation of _this(). The implementations of setValue() and getValue() are shown next in Example 6.3, “SliderSubjectImpl.cpp”.

Example 6.3. SliderSubjectImpl.cpp

  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

	Include the class declaration file, shown in Example 6.2, “SliderSubjectImpl.h”.
	When invoked, the remote caller will pass a long value, and this saves the result into the servant's storage.
	Because the subject's state has been modified, all attached observers must be notified. This is a very important step that must be taken in this method. Note that it invokes the notify() method of the parent class.
	Observers will invoke this method when requesting the current mValue.

The observer does not define its own specialized IDL interface. Instead, it makes use of the existing Tweek basic observer (tweek.ObserverPOA in Java). The method update() must be implemented. The remainder of the observer implementation is centered around communication with a SliderSubject object reference. All observer code is written in Java. The only C++ code for observers is part of the Tweek library, and it is generated entirely by the IDL compiler.

Implementing the Observer in Java

For every subject interface defined in IDL, a corresponding observer class must be written in Java. Without an observer, there is no way for the Java and C++ sides to conduct useful two-way communication. At best, the Java GUI could request a subject reference and manipulate the C++ application through the reference, but the communication would be entirely one-way.

In Example 6.4, “SliderObserverImpl.java”, we show the complete Java implementation of an observer corresponding to the tweek::SliderSubject interface defined earlier. (The JavaBean that uses this observer is explained in the section called “The JavaBean”.) The main focus of this observer is to update its contained JSlider whenever the state of the corresponding subject changes.

Example 6.4. SliderObserverImpl.java

  1 package networktest;
    
    import javax.swing.DefaultBoundedRangeModel;
    import javax.swing.JSlider;
  5 import tweek.*;
    
    /**
     * Implementation of the Observer side of the Tweek
     * Subject/Observer pattern.  It must extend tweek.ObserverPOA
 10  * so that instances of this class can be registered as CORBA
     * servants.  In addition, CORBA references to the servants must
     * be capable of being attached to remote subjects.
     */
    public class SliderObserverImpl extends ObserverPOA            
 15 {
       public SliderObserverImpl(JSlider slider,                   
                                 SliderSubject subject)
       {
          mSlider        = slider;
 20       mSliderSubject = subject;
       }
    
       /**
        * Implements the required method in tweek.ObserverPOA.  The
 25     * remote subject will invoke this method whenever it is
        * notified of a change.
        */
       public void update()                                        
       {
 30       // If we have a valid slider object, we need to update
          // its value to whatever our subject has.
          if ( mSlider != null )
          {
             DefaultBoundedRangeModel model =
 35             (DefaultBoundedRangeModel) mSlider.getModel();
             model.setValue(mSliderSubject.getValue());            
             mSlider.repaint();
          }
       }
 40 
       /**
        * Detaches this observer from our subject.  This is needed
        * when shutting down a CORBA connection.
        */
 45    public void detach()
       {
          mSliderSubject.detach(this._this());                     
       }
    
 50    private SliderSubject mSliderSubject = null;
       private JSlider       mSlider        = null;
    }

	As an observer, this class must derive from tweek.ObserverPOA. This class is generated by the IDL compiler and is part of the Tweek Network Library (see the section called “Network Library”).
	The constructor for this observer takes two arguments: a JSlider object reference and a networktest.SliderSubject object reference. The observer needs the latter argument so that it can query state information from the subject when notified of state changes. This is part of the subject/observer design pattern [Gam95].
	As stated, all observers must implement update(). This will be invoked by the remote subject when its notify() method is invoked.
	To get the updated state of the remote subject, the encapsulated subject reference's getValue() method is invoked. The value returned will be the most up-to-date information from the subject.
	It may be convenient for the observer to implement a detach() method (though the name may vary). This is used when the Java application is shutting down to ensure that the remote subject does not have dangling references to observers that no longer exist. The only action required here is invoking the subject's detach() method to inform the subject that this observer is going away.

This example demonstrates that observers do not have to be complex to be usable. While this example is purposely simple, it should illustrate that developers of observers do not necessarily have to make their implementations complicated. As will be shown in the section called “The JavaBean”, the JavaBean that uses this observer completes the picture and provides users with a GUI slider that can be manipulated by any number of simultaneous users.

Now that we have the subject and observer ready to go, we can make an application that uses them. The following example is a (relatively) simple C++ application that starts the CORBA Manager, creates the Subject Manager, registers a networktest::SliderSubject servant, and then waits for the user to press 'x' to exit. The use of exceptions may appear unfamiliar to some C++ programmers. CORBA makes use of exceptions as a cross-language mechanism to report errors, and thus, there must be proper exception handling code for the application to work correctly.

Example 6.5. SliderSubjectApp.cpp

  1 #include <tweek/CORBA/CorbaManager.h>                         
    #include <vpr/Thread/Thread.h>
    #include <vpr/Util/Debug.h>
    
  5 #include <SliderSubjectImpl.h>                                
    
    /**
     * This application starts the CORBA server for the C++ side
     * of the test.
 10  */
    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
       {
          if ( mgr.init("corba_test", argc, argv).success() )     
 20       {
             vpr::ReturnStatus status;
    
             // Once the CORBA Manager is initialized, we need to
             // create a Subject Manager.  This will hold our
 25          // SliderSubject object.
             try
             {
                status = mgr.createSubjectManager();              
    
 30             // If we were able to create the Subject Manager,
                // now we register our objects with it.
                if ( status.success() )
                {
                   // First, create real instances of the C++
 35                // object that will be the CORBA servant.  This
                   // must be allocated on the heap.
                   networktest::SliderSubjectImpl* slider_subj =
                      new networktest::SliderSubjectImpl();       
    
 40                // Now we try to register the subject and give
                   // it a symbolic, easy-to-remember name.
                   try
                   {
                      mgr.getSubjectManager()->
 45                      registerSubject(slider_subj,
                                         "SliderSubject");        
                   }
                   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.success() )
             {
                vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
 70                << "Failed to register Subject Manager instance\n"
                   << vprDEBUG_FLUSH;
             }
    
             std::cout << "Press 'x' to exit" << std::endl;
 75          char input;
    
             // 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)
 95             << "CORBA failed to initialize\n" << vprDEBUG_FLUSH;
          }
       }
       catch (...)
       {
100       vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
             << "Caught an unknown exception!\n" << vprDEBUG_FLUSH;
       }
    
       vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
105       << "Exiting\n" << vprDEBUG_FLUSH;
    
       return 0;
    }

	These two headers are typically needed. The first includes the declaration of the Tweek CORBA Manager, and the second is the subject implementation declaration, shown in Example 6.2, “SliderSubjectImpl.h”.
	In order to use CORBA through Tweek, the CORBA Manager must be created and initialized. Any number of these may be created, but in general, only one is needed per application
	After the COBRA Manager has been initialized successfully, the Tweek Subject Manager must be created.
	Once we have a valid Subject Manager, we must register subjects with it in order for object references to be passed out by CORBA. This creates the servant to which networktest::SliderSubject references will be made.
	Once the servant is created, it is registered with the Subject Manager. The Subject Manager will activate the servant within the POA so that references to it can be created and returned to clients.
	After the subject is registered, all the work is done. This application now just waits for clients to request references. It will exit when the user enters 'x'.

The application shown in Example 6.5, “SliderSubjectApp.cpp” is purposely simple. There are many ways to use the CORBA Manager and the Subject Manager. For example, an object registry could be built on top of the Subject Manager so that only specific types of servant objects may be registered. Servant registration could be automated in object constructors. The C++ API is intended to be simple to enhance its usability and flexibility, and the application shown in the example is just that: an example.

We have finally reached the point at which we implement a JavaBean that can visualize the numeric data held by the C++ slider subject. Such a JavaBean must be defined as a Tweek Panel Bean. (Refer back to Chapter 2, JavaBeans if these statements seem unfamiliar or confusing.)

The JavaBean shown in the following example is typical of one that uses the Tweek Network library to take advantage of CORBA facilities. The code for the Bean is longer than previous examples, and because of this, it will be split into multiple code blocks. Each will be discussed in turn. The full code is in one file: NetworkTest.java.

Please note that the details of setting up the GUI elements used by the Bean are left out. The code in this case was generated by JBuilder and could easily vary from Bean to Bean. For the full code, please refer to the aforementioned locations.

Imports

The slider JavaBean uses common Java Swing classes, a CORBA exception class, the Tweek Event library, the Tweek Network library, and the Java code generated by an IDL compiler. The following explains how each of these are imported into the main Bean class.

package networktest;                                       

import java.awt.*;                                         
import javax.swing.*;                                      
import javax.swing.event.*;                                
import org.omg.CORBA.BAD_PARAM;                            
import org.vrjuggler.tweek.event.*;                        
import org.vrjuggler.tweek.net.*;                          
import org.vrjuggler.tweek.net.corba.*;                    
import tweek.*;                                            

	This Bean is in a package corresponding to the IDL module defined in SliderSubject.idl. Using a consistent name throughout makes the code easier to manage and understand.
	These imports bring in common Swing and AWT GUI classes. Different Beans will use different classes and packages.
	In order to do proper narrowing of reference types, the exception org.omg.CORBA.BAD_PARAM must be caught.
	These imports bring in the classes of the Tweek Event and Network libraries.
	Tweek Java code generated by an IDL compiler will always be in the package tweek. This corresponds to the IDL module and to the C++ namespace.

Class Declaration

Now we can begin writing the Bean code. Besides the class SliderObserverImpl, this Bean has only one public class: NetworkTest. It will provide the GUI representation of the numeric data. The declaration of the class and its package-visible helper follow.

/**
 * This is an example of a JavaBean that Tweek can load dynamically.  It holds
 * a JSlider that acts as an Observer in the Tweek CORBA Subject/Observer
 * pattern implementation.
 *
 * @version 1.0
 */
public class NetworkTest
   extends JPanel                                          
   implements CommunicationListener                        
{
...
}

class FrameListener extends TweekFrameAdapter              
{
...
}

	As a Tweek Panel Bean, there must be a class that derives from javax.swing.JComponent or some subclass thereof. In this case, the superclass is javax.swing.JPanel.
	Since this Bean needs to access the remote Subject Manager, it needs to know when a CORBA service is available. By implementing org.vrjuggler.tweek.net.CommunicationListener, the Bean will be informed by the Tweek Java GUI whenever the communication state with a CORBA service changes.
	This Bean also listens for TweekFrameEvents so that it can shut itself down cleanly. To be informed of such events, a helper class that extends org.vrjuggler.tweek.event.TweekFrameAdapter exists.

Member Variables

Before delving into the methods of the networktest.NetworkTest class, it will be helpful to review the member variables used throughout the class. Refer back to this section if there is any confusion regarding the use or the type of some member variable in the method implementations.

private BorderLayout mBeanLayout = new BorderLayout();     

private JPanel mSliderPanel = new JPanel();                
private JSlider mDataSlider = new JSlider();               

private SliderObserverImpl mSliderObserver = null;         

	This is the containing layout for the entire Bean.
	The JSlider used for visually representing the subject's numeric data is mDataSlider, and it will be contained within mSliderPanel.
	The networktest::SliderSubject observer will be stored within mSliderObserver.

Note that the observer is stored in a member variable initialized to null. It will be assigned a value when a CORBA service becomes available and the corresponding subject can be requested. The object itself is stored as a member variable so that it can be accessed by all the methods of the class.

Handling CORBA Communications

The most complex part of this Bean is the handling of CORBA communication events delivered by the Tweek GUI. All of the handling in this example will be done in the methods connectionOpened() and connectionClosed(). The steps that must be followed are straightforward, but there are errors that must be handled properly. It is the error handling that can make the code look daunting, not the use of the Tweek Network library.

  1 /**
     * Implements the Tweek CommunicationListener interface needed
     * for being informed of new connections with remote ORBs.
     */
  5 public void connectionOpened(CommunicationEvent e)              
    {
       // The first thing to do is get the CORBA service object from
       // the event.  We need this so we know to whom we are are
       // connecting.  Once we have the CORBA service, we get its
 10    // Subject Manager since that's what contains the actual
       // subjects we need.
       CorbaService corba_service = e.getCorbaService();            
       SubjectManager mgr = corba_service.getSubjectManager();      
    
 15    Subject subject = mgr.getSubject("SliderSubject");           
       SliderSubject slider_subject = null;
    
       // Try to narrow the Subject object to a SliderSubject object.
       // If this fails, it throws a CORBA BAD_PARAM exception.  In
 20    // that case, we open a dialog box saying that the narrowing
       // failed.
       try
       {
          slider_subject = SliderSubjectHelper.narrow(subject);     
 25    }
       catch (BAD_PARAM narrow_ex)                                  
       {
          JOptionPane.showMessageDialog(
             null,
 30          "Failed to narrow subject to SliderSubject",
             "SliderSubject Narrow Error",
             JOptionPane.ERROR_MESSAGE
          );
       }
 35 
       // Ensure that slider_subject is a valid object just to be
       // safe.
       if ( slider_subject != null )
       {
 40       // First, we need a Java object that implements the
          // Observer.  That object must be registered with the Java
          // CORBA service.
          mSliderObserver =
             new SliderObserverImpl(mDataSlider, slider_subject);   
 45       corba_service.registerObject(mSliderObserver,
                                       "SliderObserver");           
    
          // Now that the observer is registered, we can attach it
          // to the subject.  The subject needs to know who its
 50       // observers are so that it can notify them of updates.
          slider_subject.attach(mSliderObserver._this());           
    
          // Now we set the slider in our GUI to be whatever value
          // the remote subject is holding for us.
 55       mDataSlider.setValue(slider_subject.getValue());          
          mDataSlider.addChangeListener(
             new SliderChangeListener(slider_subject)
          );                                                        
       }
 60 }
    
    /**
     * Implements the Tweek CommunicationListener interface needed
     * for being informed when existing ORB connections are closed.
 65  */
    public void connectionClosed(ConnectEvent e)                    
    {
       if ( mSliderObserver != null )
       {
 70       mSliderObserver.detach();                                 
          mSliderObserver = null;
       }
    }

	If the event delivered to the Bean is a newly opened connection, there is a new CORBA service available, so we will create a new observer to communicate through that service.
	The first step that must be taken is retrieving the org.vrjuggler.tweek.net.corba.CorbaService object from the event. This is needed as the basis for all further actions. With the CORBA service reference, we can request the Subject Manager reference. The result is a CORBA reference to the remote Subject Manager, a servant within the C++ application.
	Through the Subject Manager, we request subjects using symbolic names. In this case, we request the subject with the hard-coded name “SliderSbuject”.
	The call to getSubject() returns a reference of type tweek.Subject, but we need to narrow it to networktest.SliderSubject so we can use it. Among the code generated by the IDL compiler is a class named networktest.SliderSubjectHelper. Its narrow() method is used to narrow the CORBA reference type to a more specific type. If the narrowing fails, an exception of type org.omg.CORBA.BAD_PARAM is thrown, and it is best to handle it here.
	Once we have the subject reference, we create an observer servant that we will attach to the subject. This is where networktest.SliderObserverImpl comes into the picture.
	The observer servant must be registered with the local CORBA service so that references to it can be created. This single statement takes care of all the POA activation behind the scenes.
	Now that the servant is registered with the CORBA service, a reference to it can be passed to the remote subject in order to attach the observer to the subject.
	Once the initial references are passed around, we need to update the GUI slider to the current value held by the subject.
	As part of the collaborative slider, we need to register a change listener with the GUI slider so that it will be informed of changes made by the local user. These changes are reported to the remote subject so that other users get the update. The class SliderChangeListener is shown later.
	If the event delivered to the Bean was the closing of an existing connection, the CORBA service is being shut down. When the CORBA service is shut down, we need to detach the local observer from the remote subject to prevent further update notification attempts for this observer.

It is important to note that the use of hard-coded subject names is not recommended. In this example, the subject name is hard-coded for simplicity. The Tweek Subject Manager allows accessing code to request a list of all registered subjects. Using this information, it is possible to present the Java GUI user with a list of subjects from which they can make a selection.

Handling Frame Events

This Bean makes an effort to shut down open CORBA connections when the Tweek GUI is closed. It does this through a helper class that extends org.vrjuggler.tweek.event.TweekFrameAdapter, overriding only one method: frameClosing(). This method calls back into the NetworkTest class, invoking its own frameClosing() method. For more information about the other Tweek GUI frame events delivered through the interface org.vrjuggler.tweek.event.TweekFrameListener, refer to the Tweek Java API reference.

public class NetworkTest
   extends JPanel
   implements CommunicationListener
{
...
   public boolean frameClosing()
   {
      disconnect();
      return true;
   }
...
}

class FrameListener extends TweekFrameAdapter
{
   public FrameListener(NetworkTest bean)
   {
      this.bean = bean;
   }

   public boolean frameClosing(TweekFrameEvent e)               
   {
      return bean.frameClosing();                               
   }

   private NetworkTest bean = null;
}

	This class overrides only the method invoked when the Tweek GUI frame is closing. If this method returns false, then the GUI frame will not close.
	The handling of the frame closing event is delegated to NetworkTest.frameClosing(), which in turn calls NetworkTest.disconnect() to shut down the CORBA connection cleanly.

For the helper class FrameListener to be notified of Tweek GUI frame events, it must be registered with the Tweek event listener registry (a singleton). This step is performed in the NetworkTest constructor, as shown below.

public NetworkTest()
{
   try
   {
      jbInit();
   }
   catch(Exception e)
   {
      e.printStackTrace();
   }

   mFrameListener = new FrameListener(this);
   EventListenerRegistry.instance().
      registerListener(mFrameListener,
                       TweekFrameListener.class);
}

Handling Local Slider Change Events

A helper class is used to handle local change events in the slider. The class is a private inner class within the Bean and is defined as follows:

private class SliderChangeListener implements ChangeListener
{
   public SliderChangeListener(SliderSubject subject)
   {
      mSliderSubject = subject;
   }

   public void stateChanged(javax.swing.event.ChangeEvent e)
   {
      JSlider source = (JSlider) e.getSource();

      if ( ! source.getValueIsAdjusting() )                     
      {
         mSliderSubject.setValue(source.getValue());            
      }
   }

   private SliderSubject mSliderSubject = null;
}

Within the stateChanged() method, we check to see if the user is done adjusting the slider. If so, the remote subject is updated so that its internal value matches that of the local slider. Other users are automatically updated when this happens.

XML File

With the Bean implementation done, the XML file that describes the Bean must be written. All Beans loaded by the Tweek Java GUI are described by an XML file. In Example 6.6, “NetworkTestBean.xml”, we show the XML file for the Bean we have been developing.

Example 6.6. NetworkTestBean.xml

<?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">
  <guipanel name="Network Tester">                              
    <file                                                       
       name="${TWEEK_BASE_DIR}/share/tweek/beans/NetworkTestBean.jar"
       class="networktest.NetworkTest" />
    <tree path="/Beans" />                                      
  </guipanel>
</beanlist>

	Well-formed XML requires this line.
	Tweek XML Bean files are beanlist documents. There must be exactly one beanlist per file, but the list itself can contain multiple Beans. In this element, we also provide the information needed to validate this document using the XML Schema beanlist.xsd. In this case, we use the schema that does not employ XML namespaces. Use of the schema for validation is optional, but it is recommended.
	The Bean we have been developing is a GUI Panel Bean, and this indicates that fact.
	To find the Bean, a path must be specified. In this example, we will put the XML and JAR files in $TWEEK_BASE_DIR/share/tweek/beans. Note the use of curly braces around the environment variable. This is required. The class attribute names the class that will be instantiated, and in this case, that is networktest.NetworkTest. This name corresponds more to the fully qualified name of the class stored within the JAR file.
	Panel Beans are loaded into a tree data structure and visualized using a viewer. This specifies the path within the tree using a UNIX-style path. The path is arbitrary and will be constructed as needed when the Bean is loaded.

After the Bean is compiled into a JAR file, the JAR file and XML file need to be copied into $TWEEK_BASE_DIR/share/tweek/beans. This is the default path that Tweek searches for Beans at startup, and it is a convenient place to put this example Bean.

With all the coding done and the code compiled, we can run the C++ application and connect multiple instances of the Tweek Java GUI to it. The steps to run the C++ application are as follows:

As in the previous example, we focus on the imported classes first. They are as follows:

package fileopentestbean;                                       

import java.awt.*;                                              
import java.io.File;                                            
import java.io.FileInputStream;                                 
import javax.swing.*;                                           
import org.vrjuggler.tweek.services.ExtensionFileFilter;        
import org.vrjuggler.tweek.beans.FileLoader;                    

	This Bean will be in the package fileopentestbean.
	These are the imports of standard Java classes. In this Bean, we need two Java file I/O classes so that we may load files.
	This line imports the Tweek Service Bean known as the ExtensionFileFilter. This provides a simplified mechanism for making file filters typically used with JFileChooser instances.
	This line imports the interface from the Tweek Bean library that we will implement.

Next, we show the class declaration and the member variables.

public class FileOpenTestBean
    extends JPanel                                              
    implements java.io.Serializable, FileLoader                 
{
   // Methods ...

   private int openFileCount = 0;                               

   private BorderLayout mMainLayout    = new BorderLayout();
   private JLabel       mBeanTitle     = new JLabel();
   private JTabbedPane  mTextContainer = new JTabbedPane();     
}

	As the primary class for a Panel Bean, this class must from javax.swing.JComponent or some subclass thereof. In this case, the class will be javax.swing.JPanel.
	JavaBeans are expected to implement java.io.Serializable, and this class does that. The more interesting interface for this example is org.vrjuggler.tweek.beans.FileLoader. By implementing this interface, the Tweek Java GUI will know that this Bean can manage files.
	This is a property of the class that keeps track of the number of currently open files.
	This Bean is capable of opening multiple files, and it will manage them with a JTabbedPane.

Now that we have the basics for the class, we can start implementing the FileLoader interface. Of the methods that must be implemented, the most complex is openRequested(). It will be shown last because of its length. We will begin instead with the simplest methods.

  1 public String getFileType()
    {
       return "Text";                                               
    }
  5 
    public boolean canOpenMultiple()
    {
       return true;                                                 
    }
 10 
    public boolean canSave()
    {
       return false;                                                
    }
 15 
    public boolean saveRequested()
    {
       return false;                                                
    }
 20 
    public boolean closeRequested()
    {
       mTextContainer.remove(                                       
          mTextContainer.getSelectedComponent()
 25    );
       openFileCount--;
       return true;
    }
    
 30 public int getOpenFileCount ()
    {
       return openFileCount;                                        
    }

	This returns the type of file (or files) that can be loaded by the Bean. In this case, we are just loading plain text files.
	This method is used to determine if the Bean can open multiple files at one time. This Bean can because of its tabbed pane.
	This method is used to determine if the Bean can save files, and this Bean does not.
	Because this Bean does not save files, it simply returns false if a save is requested.
	When a close is requested, the currently selected tab is removed and the open file count is decremented.
	This simply returns the number of currently open files.

The above are all the methods of the FileLoader interface except openRequested(). We are now ready to move on to it.

  1 public boolean openRequested()
    {
       // Initialize this to false since a lot of things can go wrong
       // in the process of opening files.  Once the file is opened
  5    // and read successfully, this can be changed to true.
       boolean opened = false;
    
       JFileChooser chooser = new JFileChooser();                   
       chooser.setMultiSelectionEnabled(false);
 10    chooser.setDialogTitle("Text File Loader");
       chooser.setFileSelectionMode(JFileChooser.FILES_ONLY);
    
       // Only load .txt files.
       ExtensionFileFilter filter =
 15       new ExtensionFileFilter("Text Files");                    
       filter.addExtension("txt");
       chooser.addChoosableFileFilter(filter);
    
       int status = chooser.showOpenDialog(this);                   
 20 
       if ( status == JFileChooser.APPROVE_OPTION )
       {
          File file = chooser.getSelectedFile();
    
 25       if ( file.canRead() )                                     
          {
             try
             {
                // Read the contents of the file into a byte[]
 30             // object.
                FileInputStream input_file =
                  new FileInputStream(file);
                byte[] file_data = new byte[(int) file.length()];
                input_file.read(file_data);                         
 35 
                // Create a text area to hold the contents of the
                // file.
                JTextArea text_area = new JTextArea();              
                text_area.setEditable(false);
 40             text_area.insert(new String(file_data), 0);
    
                // Create a scroll pane to hold the text area; add
                // it to the tabbed pane with all the other
                // previously loaded scroll panes; and make the new
 45             // scroll pane the selected component.
                JScrollPane text_comp = new JScrollPane(text_area); 
                mTextContainer.add(text_comp, file.getName());
                mTextContainer.setSelectedComponent(text_comp);
    
 50             // Our work is done.
                openFileCount++;                                    
                opened = true;
             }
             catch (java.io.FileNotFoundException ex)
 55          {
                JOptionPane.showMessageDialog(
                   null,
                   "Cannot find '" + file.getAbsolutePath() + "'",
                   "Read Error", JOptionPane.ERROR_MESSAGE
 60             );
             }
             catch (java.io.IOException ex)
             {
                JOptionPane.showMessageDialog(
 65                null,
                   "Error reading from '" + file.getAbsolutePath() +
                      "':" + ex.getMessage(),
                   "Read Error", JOptionPane.ERROR_MESSAGE
                );
 70          }
          }
          else
          {
             JOptionPane.showMessageDialog(
 75             null,
                "Cannot read from file '" +
                   file.getAbsolutePath() + "'",
                "Read Error", JOptionPane.ERROR_MESSAGE
             );
 80       }
       }
    
       return opened;
    }

	First, we create a JFileChooser that will be used to select a text file. It is configured to allow selection of only a single file each time.
	Next, we create a filter for .txt files that will be used by the file chooser.
	With those steps taken, we now open the chooser and wait for the user to select a file.
	If a readable file was chosen, we open it and read its contents into an array of bytes.
	With the bytes read, we can now put the contents of the text file into a read-only JTexArea object.
	Next, we put the JTextArea in a JScrollPane so that long files can be viewed more easily. The scroll pane is added to the tabbed pane and made the currently selected panel.
	At this point, we are done, so we increment the number of open files and set the return value to true to indicate that a file was opened successfully.

This Bean uses no CORBA code and does not require C++ code to act as a peer. This may be the case for many Panel Beans written for Tweek. Of course, this Bean could be extended to open files that are then handed off to C++ code through CORBA.

The XML file for this Bean is very simple. It simply lists the Bean file information and puts the Bean at the root of the Bean tree. The full file is shown in Example 6.7, “FileOpenTestBean.xml”.

<?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">
  <guipanel name="File Open Test Bean">
    <file
      name="${TWEEK_BASE_DIR}/share/tweek/beans/FileOpenTestBean.jar" 
      class="fileopentestbean.FileOpenTestBean" />
    <tree path="/" />
  </guipanel>
</beanlist>

As usual, we begin by defining an interface. For this example, we will use an interface that provides access to a simple string object. The server (Subject) will maintain the value of the string, and the clients (Observers) will be able to query and manipulate the string. The interface will be called CxxClientTest::StringSubject. The code for the interface is shown in Example 7.1, “StringSubject.idl”.

Example 7.1. StringSubject.idl

#ifndef _CXX_CLIENT_TEST_STRING_SUBJECT_IDL_
#define _CXX_CLIENT_TEST_STRING_SUBJECT_IDL_

#include <tweek/idl/Subject.idl>

module CxxClientTest
{
   interface StringSubject : tweek::Subject   
   {
      void setValue(in string val);           
      string getValue();                      
   };
};

#endif /* _CXX_CLIENT_TEST_STRING_SUBJECT_IDL_ */

	As with all user-defined Subjects, we derive our interface from tweek::Subject.
	These methods define the accessors for the encapsulated string value. Clients will invoke these to query and to manipulate the state of the remote Subject.

Now that we have our interface defined abstractly, we must provide a C++ implementation of the Subject. This will be done in the files StringSubjectImpl.cpp and StringSubjectImpl.h. We begin with the header file, shown in Example 7.2, “StringSubjectImpl.h”. While the example code may appear long, there is only slight variation from previous Subject implementation header files. We highlight the important bits, of course.

Example 7.2. StringSubjectImpl.h

  1 #ifndef _STRING_SUBJECT_IMPL_H_
    #define _STRING_SUBJECT_IMPL_H_
    
    #include <tweek/tweekConfig.h>
  5 
    #include <string>
    
    #include <vpr/vpr.h>
    #include <vpr/Sync/Mutex.h>
 10 #include <tweek/CORBA/SubjectImpl.h>
    #include <StringSubject.h>                                     
    
    namespace CxxClientTest
    {
 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
 20  * StringSubject.
     */
    class StringSubjectImpl
       : public POA_CxxClientTest::StringSubject                   
       , public tweek::SubjectImpl
 25 {
    public:
       StringSubjectImpl() : tweek::SubjectImpl(), mValue("")
       {
          /* Do nothing. */ ;
 30    }
    
       virtual ~StringSubjectImpl()
       {
          /* Do nothing. */ ;
 35    }
    
       /**
        * Sets this subject's internal value.
        */
 40    virtual void setValue(const char* value);                   
    
       /**
        * Returns this subject's internal value.
        */
 45    virtual char* getValue();                                   
    
       /**
        * This overriding method is needed so that the correct
        * type is returned when the _this() method is invoked.
 50     * Without this method, an object of type tweek::Subject_ptr
        * would be returned.
        */
       CxxClientTest::StringSubject_ptr _this()                    
       {
 55       return POA_CxxClientTest::StringSubject::_this();
       }
    
    private:
       std::string mValue;      /**< Our value */                  
 60 
       /** A mutex to protect mValue accesses */
       vpr::Mutex  mValueLock;                                     
    };
    
 65 } // End of CxxClientTest namespace
    
    #endif /* _STRING_SUBJECT_IMPL_H_ */

	We must be sure to include the header that defines the base class from which we will derive our implementation. Remember that this code will be generated by the IDL compiler.
	As usual, we declare our implementation so that it derives from the class generated by the IDL compiler (POA_CxxClientTest::StringSubject) and from the basic Tweek Subject implementation class (tweek::SubjectImpl).
	These are the pure virtual methods defined by POA_CxxClientTest::StringSubject that we must implement. As in previous examples, this is where we will do the work of accessing the encapsulated string value.
	As with all C++ Subject implementations, we must override the method _this() in order to return the correct type. This is critical for proper use of the specific Subject type.
	Here we have the string value that will be encapsulated within the servant instance. For convenience, we use the std::string type, though it will require careful handling of the char* data that CORBA actually passes around.
	In this Subject implementation, we are being more paranoid about concurrent accesses to mValue, so we will protect it with a mutex.

Next, we look at the very simple implementations of CxxClientTest::StringSubjectImpl::setValue() and CxxClientTest::StringSubjectImpl::getValue(). These are found in the file StringSubjectImpl.cpp, and the code is shown in Example 7.3, “StringSubjectImpl.cpp”. It is important to note the use of guards in the method implementations. These provide an exception-safe mechanism for controlling access to the data member mValue. When constructed, the guard locks the mutex passed as the argument to the constructor. When the guard goes out of scope, the mutex is automatically unlocked.

Example 7.3. StringSubjectImpl.cpp

  1 #include <vpr/Sync/Guard.h>
    #include <StringSubjectImpl.h>                              
    
    namespace CxxClientTest
  5 {
    
    void StringSubjectImpl::setValue(const char* value)
    {
       {
 10       vpr::Guard<vpr::Mutex> val_guard(mValueLock);         
          mValue = std::string(value);                          
       }
    
       // Notify any observers that our value has changed.  This
 15    // is very important.
       tweek::SubjectImpl::notify();                            
    }
    
    char* StringSubjectImpl::getValue()
 20 {
       vpr::Guard<vpr::Mutex> val_guard(mValueLock);            
       return CORBA::string_dup(mValue.c_str());                
    }
    
 25 } // End CxxClientTest namespace

	As usual, we must include our header file to get the necessary declarations.
	Within this scoped block, we lock the mValueLock using a guard and assign a new value to mValue. Upon exiting this block, the guard goes out of scope, and mValueLock is unlocked.
	As with all cases where we modify the state of the Subject, we must notify any Observers who are attached to us. Just as the comment notes, this is very important.
	Here, we return the current value of mValue. We use a guard again to simplify unlocking the mutex (it happens automatically upon return). Note that we make a copy of the memory contained in mValue using CORBA::string_dup(). Making a copy is required by CORBA.

With the Subject implemented, we now turn our attention to a C++ Observer implementation. Its implementation we will be very simple. Its update() method will query the current string value and print it to the console. The goal here is to demonstrate how to write a C++ Observer, not how to write an interesting Observer.

Example 7.4. StringObserverImpl.h

  1 #ifndef _STRING_OBSERVER_IMPL_H_
    #define _STRING_OBSERVER_IMPL_H_
    
    #include <tweek/CORBA/Observer.h>                        
  5 #include <StringSubject.h>                               
    
    class StringObserverImpl : public POA_tweek::Observer    
    {
    public:
 10    StringObserverImpl(CxxClientTest::StringSubject_var subject)
          : mSubject(subject)
       {
          /* Do nothing. */ ;
       }
 15 
       virtual ~StringObserverImpl()
       {
          /* Do nothing. */ ;
       }
 20 
       virtual void update();                                
    
       void detach()
       {
 25       mSubject->detach(_this());                         
       }
    
    private:
       CxxClientTest::StringSubject_var mSubject;            
 30 };
    
    #endif /* _STRING_OBSERVER_IMPL_H_ */

	First, we include the headers we need. The first declares the basic tweek::Observer C++ interface. The second includes the tweek::StringSubject interface. We need this header so that we can hang onto a reference to our Subject.
	Our Observer implementation derives from the basic Tweek Observer class POA_tweek::Observer. The Java equivalent is tweek.ObserverPOA. Refer to Example 6.4, “SliderObserverImpl.java” in the section called “Implementing the Observer in Java” to see the correspondence.
	The update() method must be implemented for all subclasses of POA_tweek::Observer. Here, we just declare the method; the implementation will be shown in Example 7.5, “StringObserverImpl.cpp”.
	The detach() method is provided as an easy way to detach the Observer from its Subject. Ideally, this would be done in the destructor so that the detaching process happens automatically when the Observer servant is deleted. Doing so leads to incorrect deactivation of the servant, however. Instead, we provide this method as a way to perform the detachment before servant deactivation or deletion occurs.
	Finally, we have a member variable that we will use to retain a reference our Subject. This allows the Observer to be passed around to functions without passing its Subject explicitly. Further, we will see that having a reference to the Subject is required for the update() method implementation to work.

Now, we show the implementation of StringObserverImpl::update(). This method is implemented in StringObserverImpl.cpp. While the method body is very short, we use the .cpp file to encourage the implementation of methods outside of the class declaration.

Example 7.5. StringObserverImpl.cpp

#include <iostream>
#include <StringObserverImpl.h>                     

void StringObserverImpl::update()
{
   char* cur_value = mSubject->getValue();          
   std::cout << "Current string value is now '"     
             << cur_value << "'" << std::endl;
   delete cur_value;                                
}

	As usual, we have to include our header file to get the class declaration information.
	Since update() is only called when the state of the Subject changes, we need to query its current state. Once we get the current string value back, we print it to the console. The value is enclosed in single quotes so that any leading or trailing whitespace is displayed clearly.
	Lastly, we delete the memory returned by CxxClientTest::StringSubject::getValue(). The burden for freeing this memory is on the client, as per standard CORBA operating procedure.

Finally, we look at the C++ client application. This brings everything together and makes use of the tweek::CorbaService class to contact the remote server. The application shown below is more complicated than the server because more work must done. We must initialize the local CORBA Service (the local ORB); we must pick out the correct Subject Manager reference; and we must get the correct CxxClientTest::StringSubject reference from the Subject Manager. Once all of those steps are completed, we can create an Observer servant (an instance of StringObserverImpl) and attach it to the remote Subject.

The file containing the complete client application source is client.cpp. We will examine it in three parts: the required headers, the implementation of main(), and the Subject Manager lookup.

Example 7.6. client.cpp: Required Header Files

#include <iostream>
#include <string>

#include <vpr/vpr.h>
#include <vpr/Util/Debug.h>
#include <tweek/Client/CorbaService.h>    
#include <tweek/CORBA/SubjectManager.h>   

#include <StringObserverImpl.h>           

	The key to the C++ client interface is the CORBA Service. Its declaration is found in tweek/Client/CorbaService.h.
	As in Java clients, the Subject Manager plays a vital role in getting references to remote Subjects. Note that the file we include here is generated by the IDL compiler and provides only the basic interface. We will not be using the actual Subject Manager C++ implementation here. That is only used on the server side.
	Lastly, we include the implementation of our Observer. We will be creating an instance of this class to act as the servant for an Observer reference. The servant we create will be attached to a remote Subject, just as in all Java clients.

Next, we look at the implementation of the application's main() function. This is where the bulk of the work is done. Of course, in real-world use, modularizing the code would be much better than dumping most of it in main(). For the purposes of this example, we can get by with having most of the code in main().

Note the use of try/catch blocks in the client application code. As in the case of server applications (refer to the section called “The Server Application”), we are careful about handling exceptions properly. Remember that CORBA uses exceptions extensively to indicate errors, and thus it is necessary for user code to catch them.

Example 7.7. client.cpp: Implementation of main(), Part I

  1 int main(int argc, char* argv[])
    {
       std::string ns_host, iiop_ver;
       vpr::Uint16 ns_port;
  5 
       std::cout << "Naming Service host: ";                        
       std::cin >> ns_host;
    
       std::cout << "Naming Service port (usually 2809): ";         
 10    std::cin >> ns_port;
    
       std::cout << "IIOP version (usually 1.0): ";                 
       std::cin >> iiop_ver;
    
 15    // Create the local CORBA Service using the Naming Service
       // URI information we just collected.
       tweek::CorbaService corba_service(ns_host, ns_port,          
                                         iiop_ver);
    
 20    try
       {
          // Attempt to initialize the CORBA Service.
          if ( corba_service.init(argc, argv).success() )           
          {
 25          // This will hold the reference to the Subject Manager
             // we use.
             tweek::SubjectManager_var subj_mgr =
                chooseSubjectManager(corba_service);                
    
 30          // Verify that we actually got a Subject Manager
             // reference back from chooseSubjectManager.
             if ( ! CORBA::is_nil(subj_mgr) )                       
             {
                // Request the Subject with which we will communicate.
 35             // This hard-coded Subject name is not necessarily a
                // good thing.
                tweek::Subject_var subj =
                   subj_mgr->getSubject("StringSubject");           
    
 40             // If the Subject Manager knows about the Subject
                // named above, then we are good to go.
                if ( ! CORBA::is_nil(subj) )                        
                {
                   ...  // Shown in the next example block
 45             }
             }
             // We did not get a Subject Manager reference back for
             // some reason.
             else
 50          {
                vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
                   << "No Subject Manager chosen--exiting.\n"
                   << vprDEBUG_FLUSH;
             }
 55       }
          // The CORBA Service initialization failed.
          else
          {
             vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
 60             << "CORBA Service failed to initialize\n"
                << vprDEBUG_FLUSH;
          }
       }
       catch (...)
 65    {
          vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
             << "Caught an unknown exception!\n" << vprDEBUG_FLUSH;
       }
    
 70    return 0;
    }

	Here, we query input from the user to get Naming Service information. We need the host name where the Naming Service is running, the port on which it is listening, and the version of IIOP to use. Using the values we get from the user, we can construct an instance of tweek::CorbaService. Internally, it will use the values to create a URI for looking up the Naming Service reference.
	Once we have all the necessary initialization pieces, we can construct an instance of tweek::CorbaService. Simply creating an instance of this class does not perform any CORBA-related activities. That is the next step.
	Now we initialize the local CORBA Service. We pass in argc and argv in case the user provided any CORBA-specific command-line parameters. (Any such parameters will be stripped from argv, and argc will be decremented accordingly.) If initialization succeeds, we proceed to requesting the Subject Manager reference.
	Using the CORBA Service, we choose the Subject Manager through which all Subject requests will be handled. The work for making this choice is offloaded to the helper function chooseSubjectManager(), shown in Example 7.9, “client.cpp: Implementation of chooseSubjectManager()”. For now, we just assume that we got back some reference, possibly nil, to a remote tweek::SubjectManager object. Since we do not know for sure what the state of things is on the server side or what decision the user made, we verify that we did not get back a nil reference. If we got back a valid Subject Manager reference, we can use it just as we would in a Java client to request Subject references by name.
	Next, we request the reference to the remote Subject. The symbolic name we use here is the same as that specified in the server application (not shown in this chapter). Note that using a hard-coded name in this way is not recommended, but we use it here for the sake of simplicity. Once we have a reference, we verify that it is not nil before trying to use it.

We now narrow our attention to the handling of the Subject reference that was returned by the Subject Manager. The code shown in Example 7.8, “client.cpp: Implementation of main(), Part II” comes from the “...” block in Example 7.7, “client.cpp: Implementation of main(), Part I”. At this point in the application execution, we know that we have a non-nil tweek::Subject reference, so we need to narrow it to our specific type, create an Observer servant, and attach it to the remote Subject.

Example 7.8. client.cpp: Implementation of main(), Part II

  1 StringObserverImpl* string_observer(NULL);
    PortableServer::ObjectId_var observer_id;
    
    try
  5 {
       // Attempt to narrow subj to the more specific reference type
       // CxxClientTest::StringSubject_var.  If this fails, an
       // exception will be thrown and caught below.
       CxxClientTest::StringSubject_var string_subj =
 10       CxxClientTest::StringSubject::_narrow(subj);              
    
       // Request the current value before we create the Observer.
       // In this way, we can see the persistent state maintained
       // by the Subject.
 15    char* cur_value = string_subj->getValue();
       std::cout << "Current string value is '" << cur_value << "'"
                 << std::endl;
       delete cur_value;
    
 20    // Create our Observer servant.
       string_observer = new StringObserverImpl(string_subj);       
    
       // Register the newly created servant with our ORB's POA.
       observer_id =
 25       corba_service.registerObject(string_observer,
                                       "StringObserver");           
    
       // This could be done in the StringObserverImpl constructor,
       // but we do it here in this example just to make it clear
 30    // that it is important.
       string_subj->attach(string_observer->_this());               
    
       const std::string exit_string("Q");
       std::string cur_string;
 35 
       for ( ;; )                                                   
       {
          std::cout << "Enter a string (Q to quit): ";
          std::cin >> cur_string;
 40 
          if ( exit_string != cur_string )
          {
             string_subj->setValue(cur_string.c_str());             
          }
 45       else
          {
             break;
          }
       }
 50 }
    catch (...)
    {
       vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
          << "Caught an unknown exception during object interaction!\n"
 55       << vprDEBUG_FLUSH;
    }
    
    // We're done, so now we have to clean up after ourselves.
    // The order of operations here is important.
 60 if ( NULL != string_observer )
    {
       string_observer->detach();                                   
       corba_service.unregisterObject(observer_id);                 
       delete string_observer;                                      
 65 }

	Given a non-nil Subject reference, we now need to narrow it to our specific Subject type, CxxClientTest::StringSubject. If the narrowing fails, an exception will be thrown. In that case, we are done because we did not get back a reference we can use.
	If the narrowing succeeded, then we can create an Observer servant (an instance of our class StringObserverImpl). In our local ORB, this servant will handle accesses from remote objects—namely, the Subject to which it is attached.
	Next, we register our newly created Observer servant with the POA in the local CORBA Service. We give it an arbitrary name, and it gives us a unique identifier for the servant. We will need this identifier later when the application is shutting down and cleaning up after itself.
	At long last, we can attach our Observer to the remote Subject. The mechanism for doing this is nearly identical to the Java version. The only difference is the use of the -> operator, which is not present in Java. Once the Subject knows about our Observer, it will be informed of all state changes.
	In this loop, we ask the user for input and then pass that input to the Subject's setValue() method. We do this until the user enters the string "Q", which denotes that s/he wants to quit the application.
	This is where we modify the state of the remote Subject. We pass the C string version of the user-specified string as the argument to CxxClientTest::StringSubject::setValue().
	Once the user has requested to quit the application, we need to clean up the servant we constructed earlier. First, we detach the Observer from the remote Subject. Next, we unregister our servant using the ID returned by the local CORBA Service. Finally, we delete the heap memory allocated for the servant. With that, we are done.

The last part of the client application is the choice of the Subject Manager reference to use. In this example, we put that code in the helper function chooseSubjectManager(). In this function, we request the list of valid Subject Manager references from the local CORBA Service and present the information about each one to the user. Using this information, the user selects one, and that reference is then returned to the caller. In a real-world example, the Subject Manager chooser would be much more sophisticated than what we show in Example 7.9, “client.cpp: Implementation of chooseSubjectManager()”, but for the purposes of explaining the ideas, this will suffice.

Example 7.9. client.cpp: Implementation of chooseSubjectManager()

  1 tweek::SubjectManager_var
    chooseSubjectManager(tweek::CorbaService& corbaService)
    {
       tweek::SubjectManager_var subj_mgr;
  5 
       // Request all the active Subject Manager references.
       std::list<tweek::SubjectManager_var> mgrs =
          corbaService.getSubjectManagerList();                    
    
 10    std::list<tweek::SubjectManager_var>::iterator cur_mgr;
    
       // Iterate over all the tweek::SubjectManager references we
       // have.
       for ( cur_mgr = mgrs.begin();                               
 15          cur_mgr != mgrs.end();
             ++cur_mgr )
       {
          try
          {
 20          // It is not entirely safe to assume that *cur_mgr is
             // still valid at this point, even though it was valid
             // when the mgrs list was constructed.  Hence, we test
             // it again now.
             if ( ! (*cur_mgr)->_non_existent() )                  
 25          {
                std::string response;
                const std::string proceed("y");
    
                tweek::SubjectManager::SubjectManagerInfoList_var
 30                mgr_info = (*cur_mgr)->getInfo();               
    
                std::cout << "\nSubject Manager information:"
                          << std::endl;
    
 35             // Loop over the information items and print each
                // key/value pair to the screen.
                for ( CORBA::ULong i = 0;                          
                      i < mgr_info->length();
                      ++i )
 40             {
                   std::cout << "\t" << mgr_info[i].key  << " = "
                             << mgr_info[i].value << std::endl;
                }
    
 45             std::cout << "Use this Subject Manager (y/n)? ";
                std::cin >> response;
    
                if ( proceed == response )
                {
 50                subj_mgr = *cur_mgr;                            
                   break;
                }
             }
          }
 55       catch (...)
          {
             vprDEBUG(vprDBG_ALL, vprDBG_CRITICAL_LVL)
                << "Caught an unknown exception in "
                << "chooseSubjectManager loop\n"
 60             << vprDEBUG_FLUSH;
          }
       }
    
       return subj_mgr;
 65 }

	Using the given tweek::CorbaService reference, we ask for the current list of valid tweek::SubjectManager references. The references in this list are guaranteed to be valid at the time the list was constructed.
	We use an STL iterator to loop over the list of returned tweek::SubjectManager references. This loop presents each reference in sequence and asks the user if the current reference is the one s/he wants. The loop completes when the user selects a reference or when no more references are available.
	While the list of Subject Manager references was guaranteed to have contained valid references when it was constructed, things may have changed since then. That is the nature of asynchronous programming. To be safe, we test the current Subject Manager reference to see if it still refers to an extant object. If so, we continue. If not, we skip it. This invocation of tweek::SubjectManager::_non_existent() may throw an exception, and for that reason, we enclose the body of the for loop in a try/catch block.
	It is possible for a single Naming Service to have multiple active Subject Manager references. Each of these has a unique identifier within the Naming Service, but the identifier is not human readable. To work around this, we make use of the method tweek::SubjectManager::getInfo(). This method returns a sequence of key/value pairs (both are strings) that can be used to identify which Subject Manager reference is the correct one. Here, we request this information sequence and print all the key/value pairs. With this output, the user can (hopefully) determine which Subject Manager reference to use. Note This example is purposefully simple to keep the code small. Readers are strongly encouraged to come up with much more sophisticated choosing mechanisms here. For example, the flexibility of the Subject Manager information sequence would allow choices to be made entirely in code without any interactive user feedback.
	Here, the user has selected the current Subject Manager as the correct one. We copy the reference to the subj_mgr variable. Then, we break out of the loop and return subj_mgr to the caller.

With that, we are done with our review of the C++ client API in Tweek. The use of CORBA allows Java and C++ client code to be quite similar, and this can be helpful when migrating between the two. The addition of the C++ client API in Tweek 0.13 also demonstrates one of the basic design philosophies of Tweek: clients can be written in any language without concern for the language the server uses.