/*------------------------------------------------------------------------------ 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: xmlBlaster@marcelruff.info 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 XmlTypeArr; typedef sequence 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 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. *
* This interface must be implemented by the client. *
* You have to provide three methods: update(), updateOneway() and ping() */ module clientIdl { /** * This interface needs to be implemented by the clients. *

* 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 "" * If some messages failed: "" * @exception On severe problem or on authentication deny * an XmlBlasterException is thrown, all messages * of this array are treated as lost * @see the interface.update requirement */ 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 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 * @see Addressless message-event-middleware pattern */ interface Server { /** * Asynchronous read-access method. * * The results are returned to the * Client-Callback interface via the update() method. * You need to implement the method BlasterCallback.update() * This is the push modus. * * @param xmlKey Key with attributes allowing XPath or EXACT selection
* See xmlBlaster/src/dtd/XmlKey.xml for a description * @param qos Quality of Service, flags to control subscription
* See xmlBlaster/src/dtd/XmlQoS.xml for a description * @return oid The subscription ID of your subscribed message(s)
* If you subscribed using a query, the subscription ID of this
* query handling object is returned.
* You should use this subId if you wish to unSubscribe()
* If no match is found, an empty string "" is returned. * * @see addListener in Java event model * @see addObserver in Java observer pattern * @see the interface.subscribe requirement */ XmlType subscribe(in XmlType xmlKey, in XmlType qos) raises(XmlBlasterException); /** * Synchronous read-access methods * This is the pull modus. * * @param xmlKey Key with attributes allowing XPath or EXACT selection
* See xmlBlaster/src/dtd/XmlKey.xml for a description * @param qos Quality of Service, flags to control get()
* See xmlBlaster/src/dtd/XmlQoS.xml for a description * @return Contains a sequence of 0 - n MessageUnit structs with its qos infos * @see the interface.get requirement */ MessageUnitArr get(in XmlType xmlKey, in XmlType qos) raises(XmlBlasterException); /** * if a key was subscribed forever, you can cancel your * subscription with following method * * @param xmlKey Key contains the subscription ID returned from subscribe()
* See xmlBlaster/src/dtd/XmlKey.xml for a description * @param qos Quality of Service, flags to control canceling of a subscription
* See xmlBlaster/src/dtd/XmlQoS.xml for a description * @return XML string array with the subscription id's in XML markup * @see the interface.unSubscribe requirement */ XmlTypeArr unSubscribe(in XmlType xmlKey, in XmlType qos) raises(XmlBlasterException); /** * Write-Access Method. * This triggers the method update() if subscribed (observed) by somebody * or if addressed as Point-to-Point (PtP). * If the given key oid doesn't exist, it will be automatically added, * so this covers the SQL'ish INSERT and UPDATE.

* * @param msgUnit Contains a MessageUnit struct * @return String with the key oid of the msgUnit * If you let the oid be generated, you need this information * for further publishing to the same MessageUnit
* Rejected Messages will contain an empty string "" * @see the interface.publish requirement */ XmlType publish(in MessageUnit msgUnit) raises(XmlBlasterException); /** * Write-Access Method * This triggers the method update() if observed by somebody * If the given key doesn't exist, it will be automatically added, * so this covers the SQL'ish INSERT and UPDATE. * * For performance or transaction reasons, you can send a whole array * of MessageUnit with one invocation of publishArr() * * @param msgUnit Contains a sequence of 1 - n MessageUnit structs * @return String array with the key oid's, corresponding to the index * of msgUnitArr
* If you let the oid be generated, you need this information * for further publishing to the same MessageUnit array
* Rejected Messages will contain an empty string "" * @exception On severe problem an XmlBlasterException is thrown, all messages * of this array should be treated as lost */ XmlTypeArr publishArr(in MessageUnitArr msgUnitArr) raises(XmlBlasterException); /** * Publish a message to the server. * * The oneway variant may be used for better performance, * it is not returning a value (no application level ACK). * * For performance reasons, you can send a whole array * of MessageUnit with one Invocation of publishOneway() * * @param msgUnit Contains a sequence of 1 - n MessageUnit structs */ oneway void publishOneway(in MessageUnitArr msgUnitArr); /** * Erase a MessageUnit * @return String array with the key oid's which are deleted * @see the interface.erase requirement */ XmlTypeArr erase(in XmlType xmlKey, in XmlType qos) raises(XmlBlasterException); /** * Ping to check if xmlBlaster 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); }; // interface server }; // org::xmlBlaster::protocol::corba::serverIdl /** * The xmlBlaster authentication interface. *

* Use this interface to access via login() the xmlBlaster *

* The final authentication/authorization interace is not yet specified */ module authenticateIdl { interface AuthServer { /** * @deprecated Use connect() instead */ serverIdl::Server login(in string loginName, in string passwd, in serverIdl::XmlType qosClient) raises (serverIdl::XmlBlasterException); /** * Initializes a new xmlBlaster session. (Successor of login( ... ); ) *

* @param qos Quality of Service, flags for additional client * information like client certificate (X.509), timeout etc. * Typically it contains the IOR reference to the * BlasterCallback interface or other protocol addresses * like email or http URL * @return qos information like sessionId, keys, ... * @exception XmlBlasterException if the login fails * @see xmlBlaster/src/dtd/XmlQoS.xml and dtd for qos examples * @see ConnectQosSaxFactory.java Javadoc description * @see the interface.connect requirement */ serverIdl::XmlType connect(in serverIdl::XmlType qos) raises (serverIdl::XmlBlasterException); /** * @deprecated Use disconnect() instead */ void logout(in serverIdl::Server xmlBlaster) raises (serverIdl::XmlBlasterException); /** * Disconnects the client from the xmlBlaster and closes the session. *
(Counterpart of connect( ... ); ) *

* @param sessionId The server interface handle returned in the init qos. * @param qos An optional signature etc. */ void disconnect(in string sessionId, in serverIdl::XmlType qos) raises (serverIdl::XmlBlasterException); /** * Ping to check if the authentication 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::authenticateIdl #endif // _xmlBlaster_IDL_