xmlblaster.idl

java开源的企业总线.xmlBlaster

/*------------------------------------------------------------------------------
Name:      xmlBlaster.idl
Project:   xmlBlaster.org
Task:      Server interface
Copyright: xmlBlaster.org, see xmlBlaster-LICENSE file
Comment:   String arguments should never be null, use "" instead
Compile:   JacORB Java 1.2:
              $JacORB_HOME/bin/idl -p org.xmlBlaster -d ${XMLBLASTER_HOME}/src/java xmlBlaster.idl
           VisiBroker (no JacORB should be in CLASSPATH) Java 1.2:
              ${VBROKER_PATH}/bin/idl2java -root_dir ${XMLBLASTER_HOME}/src/java xmlBlaster.idl
           MICO C++:
              $CORBACPP_HOME/bin/idl --poa --no-boa xmlBlaster.idl
           COPE Perl:
              idl2perl -imp xmlBlaster.idl
Author:    [e-mail]
Version:   $Id: xmlBlaster.idl 15026 2006-04-10 16:56:35Z ruff $
------------------------------------------------------------------------------*/

#ifndef _xmlBlaster_IDL_
#define _xmlBlaster_IDL_


#pragma prefix "org.xmlBlaster.protocol.corba"


/**
 * Declaration of common types
 */
module serverIdl
{
//This ifdef works with jacorb, but is not added to build.xml for C++ idl compilers
//#ifdef XBL_IDL_WSTRING
      // Works fine with Javaclient    -> xmlBlaster
      // but failed with MicoC++Client -> xmlBlaster, the received ConnectQos wstring was empty, is not yet resolved
//   typedef wstring XmlType; 
//#else
   typedef string XmlType;
//#endif
   typedef sequence<XmlType> XmlTypeArr;

   typedef sequence<octet> ContentType;

   /**
    * This contains all informations about a Message and the Message itself.
    *
    * @param xmlKey  Unique message key with index attributes
    * @param content The data itself (XML data, java objects, jpeg pictures ...)
    * @param qos     The Quality of Service hints to control behaviour
    * @see onMessage() method in JMS
    */
   struct MessageUnit {
      XmlType xmlKey;
      ContentType content;
      XmlType qos;
   };
   typedef sequence<MessageUnit> MessageUnitArr;


   /**
    * Exception class for xmlBlaster interface
    */
   exception XmlBlasterException
   {
      string errorCodeStr;
      string node;
      string location;
      string lang;
      string message;
      string versionInfo;
      string timestampStr;
      string stackTrace;
      string embeddedMessage;
      string transactionInfo;
      string reserved;
      // TODO: boolean isServerSide;
   };

}; // org::xmlBlaster::protocol::corba::serverIdl




/**
 * Declaration of the client Callback interface.
 * <br />
 * This interface must be implemented by the client.
 * <br />
 * You have to provide three methods: update(), updateOneway() and ping()
 */
module clientIdl
{
   /**
    * This interface needs to be implemented by the clients.
    * <p>
    * The IOR of this BlasterCallback has to be passed initially to the
    * xmlBlaster using the connect() method
    */
   interface BlasterCallback
   {
      /**
       * This update is invoked when the server calls back to the client. 
       *
       * @param sessionId To identify server (authentication)
       * @param msgUnit Contains a sequence of 1 - n MessageUnit structs
       * @return For every message "<qos><state id='OK'/></qos>"
       *         If some messages failed: "<qos><state id='ERROR'/></qos>"
       * @exception On severe problem or on authentication deny
       *            an XmlBlasterException is thrown, all messages
       *            of this array are treated as lost
       * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.update.html" target="others">the interface.update requirement</a>
       */
     serverIdl::XmlTypeArr update(in string sessionId, in serverIdl::MessageUnitArr msgUnitArr)
                                raises(serverIdl::XmlBlasterException);

      /**
       * This update is invoked when the server calls back to the client. 
       *
       * The oneway variant may be used for better performance,
       * it is not returning a value (no application level ACK).
       *
       * @param sessionId To identify server
       * @param msgUnit Contains a sequence of 1 - n MessageUnit structs
       */
     oneway void updateOneway(in string sessionId, in serverIdl::MessageUnitArr msgUnitArr);

      /**
       * Ping to check if the callback server is alive. 
       * This ping checks the availability on the application level.
       * @param qos Currently an empty string ""
       * @return    Currently an empty string ""
       */
      string ping(in string qos);
   };

}; // org::xmlBlaster::protocol::corba::clientIdl



/**
 * The xmlBlaster interface
 */
module serverIdl
{
   /**
    * This is an easy to use, message based, communication middleware interface.
    * 
    * It allows event-driven instant communication between separate modules.
    *
    * COMMENTS:
    *   It is generic to avoid future changes to the IDL.
    *
    *   This server uses the benefits of both technologies XML and CORBA.
    *
    *   It is a compromise between compile time type checking (CORBA)
    *   and runtime type checking (XML).
    *
    *   Runtime checking allows easier maintenance and migration to newer
    *   xmlBlaster Versions, compile time checking of invariant interfaces
    *   allows enhanced performance and early error checking.
    *
    *   Authentication and Authorization is supported with the separate
    *   interface  AuthServer.
    *
    *   The <key oid=""> strings have to be handled in a hierarchical manner to avoid
    *   namespace conflicts or may be generated (as number) by the xmlBlaster-server.
    *
    * BENEFITS:
    *   xmlBlaster allows instant communication between different uncoupled modules
    *   spread over the Internet (publish / subscriber and point to point framework).
    *
    *   For example:
    *   - Clipboard functionality to store permanent the clipboard entries
    *     of many clients
    *   - Task handling
    *     This feature allows automatic notification, when a task
    *     for a special user is available.
    *   - Inter client communication (chat rooms, graphic rooms etc.)
    *   - Broadcasts over well known attribute-keys
    *     or by notifying all known client-callback interfaces
    *   - email like instant notifications
    *   - inter process 'model/view/controller' paradigm
    *   - synchronize html with embedded applets over the server
    *   - data and message transfer between subsystems
    *   - controller support functionality like subsystem-alive slots,
    *     start and stop events etc.
    *   - configuration attributes with auto-notification
    *   - Central logging facility for client/server systems
    *   - Radar tracking systems
    *
    * RELATED DESIGN PATTERNS:
    *   @see JMS - Java Message Service, http://java.sun.com/products/jms/
    *   @see JMQ - A reference implementation of JMS, http://www.sun.com/workshop/jmq/
    *   @see JNDI - Java Naming & Directory Interface, www.javasoft.com/products/jndi
    *   @see Observer Pattern, Gamma et.al
    *   @see CORBA Property Service, http://www.omg.org
    *   @see CORBA Notification Service ftp://ftp.omg.org/pub/docs/telecom/98-01-01.pdf
    *   @see CORBA Event Service (push/pull concepts), http://www.omg.org
    *   @see CORBA Design Patterns, Mowbray Thomas J. et al. 'Dynamic Attributes'
    *   @see CORBA Messaging Service