i_xmlblasteraccess.java

java开源的企业总线.xmlBlaster

   /**
    * The public session ID of this login session.
    * This is a convenience method only, the information is from ConnectReturnQos or if not available
    * from ConnectQos.
    * @return null if not known
    * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/client.failsafe.html">client.failsafe requirement</a>
    */
   SessionName getSessionName();

   String getStorageIdStr();

   /**
    * Allows to set a unique client side queue name (connection queue).
    * Useful only if you code connects to multiple servers with the same login name.
    * Use with very caution to be unique in complete database!
    * @param prefix For example "toserver1"+sessionName.getRelativeName()
    */
   void setStorageIdStr(String prefix);

   /**
    * Allows to set the node name for nicer logging.
    * Used for clustering.
    * @param nodeId For example "/xmlBlaster/node/heron"
    */
   void setServerNodeId(String nodeId);

   /**
    * The cluster node id (name) to which we want to connect.
    * <p />
    * Needed only for nicer logging when running in a cluster.<br />
    * Is configurable with "-server.node.id golan"
    * @return e.g. "golan", defaults to "xmlBlaster"
    */
   String getServerNodeId();

   //SubscribeReturnQos subscribe(java.lang.String xmlKey, java.lang.String qos) throws XmlBlasterException;
   /**
    * Subscribe to messages.
    * <p>
    * The messages are delivered asynchronous with the update() method.
    * </p>
    * @param subscribeKey Which message topics to retrieve
    * @param subscribeQos Control the behavior and further filter messages with mime based filter plugins
    * @return Is never null
    * @see org.xmlBlaster.client.I_Callback#update(String, org.xmlBlaster.client.key.UpdateKey, byte[], org.xmlBlaster.client.qos.UpdateQos)
    * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.subscribe.html">interface.subscribe requirement</a>
    * @throws XmlBlasterException like ErrorCode.USER_NOT_CONNECTED and others
    */
   SubscribeReturnQos subscribe(SubscribeKey subscribeKey, SubscribeQos subscribeQos) throws XmlBlasterException;

   /**
    * This subscribe variant allows to specify a specialized callback
    * for updated messages.
    * <p />
    * This way you can implement for every subscription a specific callback,
    * so you don't need to dispatch updates when they are received in only one central
    * update method.
    * <p />
    * Example:<br />
    * <pre>
    *   XmlBlasterAccess con = ...   // login etc.
    *   ...
    *   SubscribeKey key = new SubscribeKey(glob, "//stock", "XPATH");
    *   SubscribeQos qos = new SubscribeQos(glob);
    *   try {
    *      con.subscribe(key, qos, new I_Callback() {
    *            public String update(String name, UpdateKey updateKey, byte[] content, UpdateQos updateQos) {
    *               System.out.println("Receiving message for '//stock' subscription ...");
    *               return "";
    *            }
    *         });
    *   } catch(XmlBlasterException e) {
    *      System.out.println(e.getMessage());
    *   }
    * </pre>
    * <p />
    * NOTE: You need to pass a callback handle on login as well (even if you
    * never use it). It allows to setup the callback server and is the
    * default callback deliver channel for PtP messages.
    * <p />
    * NOTE: On logout we automatically unSubscribe() this subscription
    * if not done before.
    * @param cb      Your callback handling implementation
    * @return SubscribeReturnQos with the unique subscriptionId<br>
    *                If you subscribed using a query, the subscription ID of this<br>
    *                query handling object (SubscriptionInfo.getUniqueKey()) is returned.<br>
    *                You should use this ID if you wish to unSubscribe()
    *         Is never null
    * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.subscribe.html">interface.subscribe requirement</a>
    * @throws XmlBlasterException like ErrorCode.USER_NOT_CONNECTED and others
    */
   SubscribeReturnQos subscribe(SubscribeKey subscribeKey, SubscribeQos subscribeQos, I_Callback cb) throws XmlBlasterException;

   /**
    * Subscribe to messages.
    * @param xmlKey Which message topics to retrieve
    * @param xmlQos Control the behavior and further filter messages with mime based filter plugins
    * @return is never null
    * @see I_XmlBlasterAccess#subscribe(SubscribeKey, SubscribeQos, I_Callback)
    * @throws XmlBlasterException like ErrorCode.USER_NOT_CONNECTED and others
    */
   SubscribeReturnQos subscribe(String xmlKey, String xmlQos, I_Callback cb) throws XmlBlasterException;

   /**
    * Access synchronously messages. They are on first request subscribed
    * and cached on client side.
    * <p>
    * A typical use case is a servlet which receives many HTML requests and
    * usually the message has not changed. This way we avoid asking xmlBlaster
    * every time for the information but take it directly from the cache.
    * </p>
    * <p>
    * The cache is always up to date as it has subscribed on this topic
    * </p>
    * <p>
    * You need to call <i>createSynchronousCache()</i> before using <i>getCached()</i>.
    * </p>
    * <p>
    * NOTE: Passing two similar getKey but with different getQos filters is currently not supported.
    * </p>
    * <p>
    * NOTE: GetKey requests with EXACT oid are automatically removed from cache when
    *       the topic with this oid is erased. XPATH queries are removed from cache
    *       when the last topic oid which matched the XPATH disappears.
    * </p>
    * @param getKey Which message topics to retrieve
    * @param getQos Control the behavior and further filter messages with mime based filter plugins
    * @return An array of messages, the sequence is arbitrary, never null
    * @throws XmlBlasterException if <i>createSynchronousCache()</i> was not used to establish a cache first
    * @see #createSynchronousCache(int)
    * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/client.cache.html">client.cache requirement</a>
    * @throws XmlBlasterException like ErrorCode.USER_NOT_CONNECTED and others
    */
   public MsgUnit[] getCached(GetKey getKey, GetQos getQos) throws XmlBlasterException;

   //MsgUnit[] get(java.lang.String xmlKey, java.lang.String qos) throws XmlBlasterException;
   /**
    * Get synchronous messages.
    * @param getKey Which message topics to retrieve
    * @param getQos Control the behavior and further filter messages with mime based filter plugins
    * @return never null
    * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.get.html">interface.get requirement</a>
    * @throws XmlBlasterException like ErrorCode.USER_NOT_CONNECTED and others
    */
   MsgUnit[] get(GetKey getKey, GetQos getQos) throws XmlBlasterException;

   // @param maxBytes The total size of all returned messages together must not exceed this value.
   //       This is not implemented yet since the size of the entries in the queue is not guaranteed
   //       to be related to the size of the MsgUnits
   //RELATING_CALLBACK = "callback";
   //RELATING_SUBJECT = "subject";
   //RELATING_HISTORY = "history";
   /**
    * This method synchronously accesses maxEntries messages from any xmlBlaster server side queue.
    * <p>
    * This is a convenience method which uses get() with a specific Qos.
    * <p>Important note:<br />
    * Currently you shouldn't use unlimited timeout==-1 as this could
    * lead to a server side thread leak on client disconnect.
    * As a workaround please use a loop and a timeout of for example 60000
    * and just ignore returned arrays of length 0.
    * </p>
    * @param oid The identifier like
    *            "topic/hello" to access a history queue,
    *            "client/joe" to access a subject queue or
    *            "client/joe/session/1"
    *            to access a callback queue.
    *            The string must follow the formatting rule of ContextNode.java
    * @param maxEntries The maximum number of entries to retrieve
    * @param timeout The time to wait until return.
    *                If you choose a negative value it will block until the maxEntries
    *                has been reached.
    *                If the value is '0' (i.e. zero) it will not wait and will correspond to a non-blocking get.
    *                If the value is positive it will block until the specified amount in milliseconds
    *                has elapsed or when the maxEntries has been reached (whichever comes first).
    * @param consumable  Expressed with 'true' or 'false'.
    *                    If true the entries returned are deleted from the queue
    * @return An array of messages, is never null but may be an array of length=0 if no message is delivered
    * @see org.xmlBlaster.util.context.ContextNode
    * @see <a href="http://www.xmlblaster.org/xmlBlaster/doc/requirements/engine.qos.queryspec.QueueQuery.html">engine.qos.queryspec.QueueQuery requirement</a>
    * @see javax.jms.MessageConsumer#receive
    */
   MsgUnit[] receive(String oid, int maxEntries, long timeout, boolean consumable) throws XmlBlasterException;


   //UnSubscribeReturnQos[] unSubscribe(java.lang.String xmlKey, java.lang.String qos) throws XmlBlasterException;
   /**
    * Cancel subscription.
    * @param unSubscribeKey Which messages to cancel
    * @param unSubscribeQos Control the behavior
    * @return The status of the unSubscribe request, is never null
    * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.unSubscribe.html">interface.unSubscribe requirement</a>
    * @throws XmlBlasterException like ErrorCode.USER_NOT_CONNECTED and others
    */
   UnSubscribeReturnQos[] unSubscribe(UnSubscribeKey unSubscribeKey, UnSubscribeQos unSubscribeQos) throws XmlBlasterException;

   /**
    * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.publish.html">interface.publish requirement</a>
    */
   PublishReturnQos publish(MsgUnit msgUnit) throws XmlBlasterException;
   //Rename publishArr() to publish
   //PublishReturnQos[] publish(org.xmlBlaster.util.MsgUnit[] msgUnitArr) throws XmlBlasterException;
   /**
    * Publish messages.
    * @param msgUnitArr The messages to send to the server
    * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.publish.html">interface.publish requirement</a>
    * @throws XmlBlasterException like ErrorCode.USER_NOT_CONNECTED and others
    */
   void publishOneway(org.xmlBlaster.util.MsgUnit [] msgUnitArr) throws XmlBlasterException;

   /**
    * Publishes one message in streaming manner, if the message content is too big to fit in one single chunk, the message
    * is split in several smaller messages (called chunks) and these are published. During the publishing of these messages,
    * the method blocks.
    * 
    * @param is The input stream from which to read the input data.
    * @param keyData The key for the message (same for all chunks)
    * @param qosData The qos for all messages (same for all chunks besides internal stuff added in this method)
    * @param maxBufSize The maximum content size of each chunk.
    * @param contentReplacer an optional content replacer (i.e. a modifier of the content) can be null.
    * @return an array containing the return qos. Currently an array of length 1 is returned containing the return qos for
    * the first message.
    * @throws XmlBlasterException
    */
   PublishReturnQos[] publishStream(InputStream is, MsgKeyData keyData, MsgQosData qosData, int maxBufSize, I_ReplaceContent contentReplacer) throws XmlBlasterException;

   /**
    * Implements the blocking request/reply pattern.
    * <p>
    * The msgUnit should contain a PublishQos which routes the request
    * to the desired client, for example sending it to client <code>joe</code>
    * and its login session <code>1</code>:
    * <pre>
    * import org.xmlBlaster.util.qos.address.Destination;
    * import org.xmlBlaster.client.qos.PublishQos;
    *  ...
    *  Global glob = ...;
    *  ...
    *  PublishQos pq = new PublishQos(glob);
    *  Destination dest = new Destination(glob, new SessionName(glob, "joe/1"));
    *  dest.forceQueuing(true);
    *  pq.addDestination(dest);
    *  </pre>
    *  <p>
    *  This receiver needs to send the response to the topic oid as passed with
    *  the client property "__jms:JMSReplyTo":
    *  <pre>
    *  String tempTopicOid = updateQos.getClientProperty(Constants.JMS_REPLY_TO, "");
    *  // Send reply back ...
    *  PublishKey pk = new PublishKey(glob, tempTopicOid);
    *  ...
    *  </pre>
    *
    *  <p>
    *  This approach is similar to the JMS approach for request/reply (TopicRequestor.java)
    *  but we have the choice to send the msgUnit directly to another client or to a topic (as JMS),
    *  and we can handle multiple replies for one request.
    *  <p>
    *  The feature is implemented on client side with a temporary response topic and a <code>receive()</code> call.
    *  Please note the timeout limitation as described at
    *  {@link #receive(String, int, long, boolean)})
    *
    * @param msgUnit The request to send
    * @param timeout The milliseconds to block, 0 is none blocking, -1 blocks forever
    * @param maxEntries The maximum number of entries to deliver or return with less after timeout
    * @return The response messages, typically one.
    * @see <a href="http://www.xmlBlaster.org/xmlBlaster/demo/HelloWorld8.java.html">HelloWorld8.java</a>
    */
   MsgUnit[] request(MsgUnit msgUnit, long timeout, int maxEntries) throws XmlBlasterException;

   //EraseReturnQos[] erase(java.lang.String xmlKey, java.lang.String qos) throws XmlBlasterException;
   /**
    * @param eraseKey The topics to erase
    * @param eraseQos Control the erase behavior
    * @return The status of the erase request, is never null
    * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.erase.html">interface.erase requirement</a>
    * @throws XmlBlasterException like ErrorCode.USER_NOT_CONNECTED and others
    */
   EraseReturnQos[] erase(EraseKey eraseKey, EraseQos eraseQos) throws XmlBlasterException;

   /**
    * Access the environment settings of this connection.
    * <p>Enforced by interface I_ConnectionHandler</p>
    * @return The global handle (like a stack with local variables for this connection)
    */
   Global getGlobal();

   /**
    * Dump state of this client connection handler into an XML ASCII string.
    * @return internal state
    */
   String toXml();
}