$Id$

Documentation for the Simulator/DOVE demo

Purposes: 1) To show how the event service can be used to as a medium to
          transport monitoring events including data.
          2) To show how objects implemented in Java can access/can be accessed
          by TAO objects.
          3) To show the feasability of the DOVE framework as mentioned in
          http://www.cs.wustl.edu/~schmidt/dove.html and
          http://www.cs.wustl.edu/~schmidt/DOVE_and_LifeCycleService.ps.gz
          4) To serve as a visual demonstration tool for scheduling and event
          service configurations and applications.

Application: Using the Event Service as distribution media, event
             consumers and event suppliers are needed. The central
             element in the Event Service is a so called, event channel.
             The event channel transports events from suppliers to
             consumers. Filtering can be activated.
             The mapping to DOVE is the following:
             Event Channel -    DOVE Agent
             DOVE Browser
             and/or DOVE MIB -  Monitor/Event Consumer
             Event Supplier -   Monitored Application (here
                                an object supplying recorded scheduling
                                and dummy information)
             Logging Supplier - Monitored Application (here an object supplying
                                creation times and updating a flag to record
                                actual EC arrival and dispatching times in
                                the scheduling information data structure
                                viewed by the browser)
             Dual EC Supplier - Monitored Application (here an object supplying
                                separate Navigation and Weapons data sets
                                in separate generating threads, which use
                                separate push
                                viewed by the browser)

Implementation:
             The events contain structs with avionics information.
             They are generated by the monitored application and are
             consumed by the DOVE Browser, a JAVA applet or application running
             on a different machine and/or location. The collected metrics are
             displayed in the Browser.

             When an event arrives from the event supplier, a consumer inspects
             the data field in the event. The field is a CORBA::Any, so
             no assumptions can be made about the kind of data in the event.

             A C++ Supplier pushes events containing a
             navigation or weapons struct to the Event Service.
             The latency and other machine metrics are read from
             a file, which contains recorded scheduling information.
             The Event Service  dispatches the events to any number of
             DOVE Browsers/MIBs which are implemented using JAVA/C++.
             The DOVE Browser extracts the data of the structs and dispatches
             it to various Visualization Components.


For more information refer to:
        $TAO_ROOT/docs/releasenotes/index.html


Requirements:
           * C++ compiler
           * ACE/TAO environment,
           * Visibroker 3.2+ for Java

!!RELEASE CHANGES:
        - the file make.bat has been expanded for use on NT

        - the file ss has been moved one level up and it got
          renamed to "start_services". So use it to start the
          naming and event service.

        - it is no longer required to start the scheduling service

        - the file make.bat has been expanded and refined for use on NT
          The following make targets are defined:
            make clean - removes all class files and idl generated java files
            make realclean - updates idl files, does a make clean
            make vb - makes the browser, using visibroker for java
            make vbjava - remakes only the java files using vbjc
            make jdk - makes the browser, using jdk
                       (the demo does not currently work with jdk)

Parts of the Demo:

        * DOVE Browser (implemented in Java using Visibroker 3.2/3.3 for Java)

        * Event Supplier, can be seen as a monitored object, called
          DOVE Application (implemented in C++ using TAO)

        * Logging Supplier, can be seen as a monitored object, called
          DOVE Application (implemented in C++ using TAO) - rather than
          providing canned simulation data, allows the actual EC arrival and
          dispatching information to be recorded in the scheduling data

        * Dual EC Supplier, can be seen as a monitored object, called
          DOVE Application (implemented in C++ using TAO) - provides a paired
          event and scheduling services for control over event prioritization.

        * DOVE MIB, storing event data on persistent storage and keeping
          track of statistical data (implemented in C++ using TAO)

Files:
        Common:
        NavWeap.idl - IDL definition of the Weapons and Navigation structures
        README - this readme file

        Event Supplier:
          (in directory  $TAO_ROOT/orbsvcs/tests/Simulator/Event_Supplier/)
        DualEC_Sup.cpp - Dual EC Event Supplier
        DualEC_Sup.h   - Dual EC Event Supplier class definitions
        Event_Sup.cpp - Event Supplier
        Event_Sup.h   - Event Supplier class definition
        Logging_Sup.cpp - Event Supplier for EC logging
        Logging_Sup.h   - Event Supplier for EC logging class definition
        Makefile      - Event Supplier Makefile
        (Event_Con.cpp, Event_Con.h - Event Consumer for testing)
        svc.conf - helper file

        DOVEBrowswer:
          (in directory  $TAO_ROOT/orbsvcs/tests/Simulator/DOVEBrowser/)
                AnswerEvent.java  - Having my own Events
                AnswerListener.java - Listener for these Events
                DataHandler.java  - Base class for all Data Handlers
                DemoCore.java - Core of the Demo to connect Observables
                                with Observers
                DemoObservable.java - Base class for Observables
                DoubleVisComp.java  - Visualization Component
                                      (will be a JavaBean) for Doubles
                DOVEBrowser.java - Wrapper around DemoCore
                DOVEBrowserApplet.java - Applet wrapper around DemoCore
                MTQueue.java - synchronized queue for multi-threaded access
                MTDataHandlerAdapter.java - uses the Adapter and Active Object
                                            patterns to provide early demuxing
                                            of ORB upcalls onto multiple
                                            synchronized queues managed by
                                            data handler threads
                NS_Resolve.java  - Resolving the inital reference
                                   to the Naming Service
                NavWeapDataHandler.java  - Specialized Data Handler for
                                           Navigation and Weapons data
                NavigationVisComp.java - Visualization Component
                                         (... JavaBean) for Navigation data
                ObservablesDialog.java - Dialog window for connecting
                                         Observables with OBservers
                Properties.java - constant definitons
                PushConsumer.java - Event Service Push Consumer
                PushConsumerFactory.java - Factory for the Consumer
                Queue.java - Queue for the DoubleVisComp
                VisComp.java - Base class for the Visualization Components
                WeaponsVisComp.java - Visualization Component for Weapons


        DOVE MIB:
          (in directory  $TAO_ROOT/orbsvcs/tests/Simulator/DOVEMIB/)
                DOVEMIB.[cpp,h] - Core routines, connection to the
                                  Event Channel
                Node.[cpp,h] - Nodes used by the AnyAnalyser
                AnyAnalyser.[cpp,h] - Anaylser for CORBA anys, storing the
                                      contained types in persistent storage
                NodeVisitor.h - base class definition of a Visitor
                PrintVisistor.[cpp,h] - Able to print a given tree
                                        of type nodes, which is
                                        generated by the Any analyser


Compiling:
        Common:
                Be sure that you have _not_ built with
                TAO_LACKS_EVENT_CHANNEL_ANY enabled.

                And, be sure that the following are built:

                "compile $TAO_ROOT/orbsvcs/orbsvcs"
                "compile $TAO_ROOT/orbsvcs/Event_Service"
                "compile $TAO_ROOT/orbsvcs/Naming_Service"
                "compile $TAO_ROOT/orbsvcs/Scheduling_Service"

        UNIX platforms:

                Then, just run "make" in top level Simulator
                directory.  The DOVEBrowser requires VisiJava's
                idl2java and vbjc.  If they are not on your PATH,
                or in the default location specified in
                DOVEBrowser/Makefile, you'll have to specify the
                location in the "make" invocation.  For example:

                  make VISIJAVA_BIN=/usr/local/VisiJava-3.2

        NT:
                Open the Event_Sup.dsw workspace found in the
                Event_Supplier directory in MSVC++ 5.0+ and build
                the Event_Sup, Logging_Sup, and DualEC_Sup projects.

                From a console window, change to the DOVEBrowser
                directory and run "make vb" to build the browser using
                Visibroker.  The first time you do this, you will need to
                run "make setup" to copy the correct files into the directory.
                You may also want to do a "make realclean" each time you
                rebuild in case there were changes to IDL files.

Starting:

        Start in the following order on different ORB ports:
                * Naming Service
                * Event Service

                You can use "start_services" on Unix machines. The
                script is located in $TAO_ROOT/orbsvcs/tests.

        Event Supplier (simulation data):
                Event_Sup -f MLF.dat -m 1000

                // -m 1000 for 1000 events sent by the supplier
                // -f MLF.dat to read scheduling data from this file as input


        Logging Supplier (live latency and latency jitter data):
                Logging_Sup -f MLF.dat -m 1000

                // -m 1000 for 1000 events sent by the supplier
                // -f MLF.dat to read operation names from this file as input


        Dual EC Supplier (live latency and jitter data over two channels):
                DualEC_Sup -f MLF.dat -m 1000

                // -m 1000 for 1000 events sent by the supplier
                // -f MLF.dat to read operation names from this file as input

        DOVE Browser:
                vbj DOVEBrowser
                (also supported: vbj DOVEBrowser -nameserviceior <IOR>
                                 vbj DOVEBrowser -nameserviceport <port>
                                 vbj DOVEBrowser -dualECdemo)

                or

                gatekeeper
                cd /visigenic/vbroker/lib
                jar xf vbjorb.jar
                jar xf vbjtools.jar
                "setting the Naming Service IOR in the DOVEBrowser.html file"
                appletviewer DOVEBrowser.html



        DOVE MIB:
                DOVEMIB -f myfile -m 100

                // -m 100 for storing the next 100 events
                // -f <name of the file in which it will be stored>

