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.

  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;
    }

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.

  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

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.

  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;
    }

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.

  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) )               
 20       {
             bool status(false);
    
             // 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 )
                {
                   // 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 )
             {
                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;
    }

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.

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 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              
{
...
}

private BorderLayout mBeanLayout = new BorderLayout();     

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

private SliderObserverImpl mSliderObserver = null;         

  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;
       }
    }

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;
}

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

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

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;
}

<?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>

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;                    

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();     
}

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;                                        
    }

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;
    }

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”.

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

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.

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

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.

  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

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.

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

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.

#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;                                
}

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.

#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>           

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.

  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) )                     
          {
 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;
    }

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.

  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 }

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.

  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 }

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.