TWiki . Jxta . JxtaCQoS

The idea behind this design is that each message can be labeled with a set of QoS requirement, each point the message passed by will do it's best to support the QoS. Note this is a best effort, there ie no guarantee that each peer along the path can support all the QoS needed.

However, it should be possible to implement some sort of negotiation protocol in the future, but that is not in scope of this document.

QoS schema

<xs:schema xmlns:jxta="http://www.jxta.org" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.jxta.org">
  <xs:element name="QoS_Setting" type="jxta:QoS_Setting" />
  <xs:element name="QoS_Support" type="jxta:QoS_Support" />
  <xs:element name="QoS" type="xs:string" />

  <xs:complexType name="QoS_Support">
    <xs:sequence>
      <xs:element ref="jxta:QoS" minOccurs="0" maxOccurs="unbounded" />
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="QoS_Setting">
    <xs:sequence minOccurs="0" maxOccurs="unbounded">
      <xs:element ref="jxta:QoS" />
      <xs:element name="Value" type="xs:string" />
    </xs:sequence>
  </xs:complexType>
</xs:schema>

QoS Capability

Each capability is defined as a name and value pair. Within this spec, we define a few capability to be supportted.

jxtaMsg:priority: the priority of the message. Valid range from 0 to 65535, lower the value with lower priority.

jxtaMsg:TTL: the number of hops of a message can have before to be discard. The maximum hop of the message can have. The TTL will be decreased by one when a message was received from the wire. Before a message was sent to wire, TTL is checked to be greater than 0. The message will be discard if the TTL reach 0.

jxtaMsg:lifespan: the timestamp of a message to be discard, the value should be the seconds since epoch. The timestamp(seconds after the epoch, 0:0:0 UTC, Jan 1, 1970) for the message to be dropped. The timestamp was checked against local clock before it was sent to as well as when it was received from the wire, and would be discard if current time passed the timestamp. For lifespan to work properly across the network, the network needs to have synchronized clock.

jxtaTransport:bandwidth: the desired bandwidth in Kb.

jxtaTransport:latency: the acceptable latency in ms for a msg waiting to be processed.

QoS API

With the latest API design, it is now easier to use constant settings. By creating Jxta_QoS structure with desired QoS requirement, developer can easily create a set of different setting and apply them to messages easily instead of requiring directly manipulate each message.

For some services not taking Jxta_message as parameters, like discovery/resolver, we will need to define new APIs to give them QoS granularity at message level.

Jxta_QoS

/*
 * Copyright (c) 2006 Sun Microsystems, Inc.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The end-user documentation included with the redistribution,
 *    if any, must include the following acknowledgment:
 *       "This product includes software developed by the
 *       Sun Microsystems, Inc. for Project JXTA."
 *    Alternately, this acknowledgment may appear in the software itself,
 *    if and wherever such third-party acknowledgments normally appear.
 *
 * 4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA" must
 *    not be used to endorse or promote products derived from this
 *    software without prior written permission. For written
 *    permission, please contact Project JXTA at http://www.jxta.org.
 *
 * 5. Products derived from this software may not be called "JXTA",
 *    nor may "JXTA" appear in their name, without prior written
 *    permission of Sun.
 *
 * THIS SOFTWARE IS PROVIDED AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL SUN MICROSYSTEMS OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of Project JXTA.  For more
 * information on Project JXTA, please see
 * <http://www.jxta.org/>.
 *
 * This license is based on the BSD license adopted by the Apache Foundation.
 *
 * $Id: JxtaCQoS.txt,v 1.4 2006/09/30 05:37:32 slowhog Exp root $
 */

#ifndef JXTA_QOS_H
#define JXTA_QOS_H

#include "jxta_apr.h"
#include "jxta_types.h"

#ifdef cplusplus
extern "C" {
#if 0 
};
#endif
#endif

typedef struct jxta_QoS Jxta_QoS;

/**
 * Create a QoS structure
 * @param me The pointer to receive the created structure
 * @param p The apr_pool_t structure which to be used with the structure, this pool must out-live the created QoS structure.
 * 
 * @return JXTA_SUCCESS if the operation succeed. 
 */
JXTA_DECLARE(Jxta_status) jxta_QoS_new(Jxta_QoS ** me, apr_pool_t *p);

/**
 * Create a QoS structure, and initiliaze the structure by parsing from the XML.
 * @param me The pointer to receive the created structure
 * @param xml The XML paragraph of QoS_Setting or QoS_Support
 * @param p The apr_pool_t structure which to be used with the structure
 * 
 * @return JXTA_SUCCESS if the operation succeed. JXTA_INVALID_ARGUMENT if the XML is not one of the type, JXTA_FAILED if other
 * error occurs.
 */
JXTA_DECLARE(Jxta_status) jxta_QoS_new_1(Jxta_QoS **me, const char *xml, apr_pool_t *p);

/**
 * Destroy a QoS structure
 */
JXTA_DECLARE(Jxta_status) jxta_QoS_destroy(Jxta_QoS * me);

/**
 * Clone a QoS structure
 * @param me The pointer to receive the created structure
 * @param src The Jxta_QoS to be cloned
 * @param p The apr_pool_t structure which to be used with the structure, this pool must out-live the created QoS structure.
 * 
 * @return JXTA_SUCCESS if the operation succeed. 
 */
JXTA_DECLARE(Jxta_status) jxta_QoS_clone(Jxta_QoS ** me, const Jxta_QoS * src, apr_pool_t *p);

/**
 * Set a value of a QoS capability for the QoS structure
 * @param me pointer to the Jxta_QoS structure
 * @param name The QoS capability to be set
 * @param value The QoS value to be set
 * @param overwrite Whether or not to overwrite the current setting. If the value is FALSE, the value will be set only if it has
 * not been set before.
 * @return JXTA_SUCCESS if the value was set. JXTA_BUSY if the value has been set and overwrite is FALSE
 */
JXTA_DECLARE(Jxta_status) jxta_QoS_set(Jxta_QoS * me, const char * name, const char * value, Jxta_boolean overwrite);

/**
 * Get a value of a QoS capability for the QoS structure
 * @param me pointer to the Jxta_QoS structure
 * @param name The QoS capability to retrieve
 * @param value A pointer to receive the QoS value 
 * @return JXTA_SUCCESS with the value. JXTA_ITEM_NOTFOUND if the value is not set.
 */
JXTA_DECLARE(Jxta_status) jxta_QoS_get(const Jxta_QoS * me, const char * name, const char ** value);

/**
 * Convert the current setting into a jxta:QoS_Setting XML paragraph. A sample is like:
 *  <QoS_Setting>
 *    <QoS>lifespan
 *      <Value>1152583254</Value>
 *    </QoS>
 *    <QoS>priority
 *      <Value>128</Value>
 *    </Qos>
 *  </QoS_Setting>
 * The string will be allocated from the pool assigned when create the QoS object
 * @param me pointer to the Jxta_QoS structure
 * @param result A pointer to receive the result NULL-terminate string.
 * @param p The apr_pool_t structure used in the operation, from which the string will be allocated. NULL is allowed, for which
 * case the same apr_pool_t used to create the Jxta_QoS strcture will be used.
 * @return JXTA_SUCCESS with the value. JXTA_FAILED if error occurs.
 */
JXTA_DECLARE(Jxta_status) jxta_QoS_setting_to_xml(const Jxta_QoS * me, char ** result, apr_pool_t *p);

/**
 * Convert the current capability into a jxta:QoS_Support XML paragraph. A sample is like:
 *  <QoS_Support>
 *    <QoS>lifespan</QoS>
 *    <QoS>priority</QoS>
 *    <QoS>TTL</QoS>
 *  </QoS_Support>
 * The string will be allocated from the pool assigned when create the QoS object
 * @param me pointer to the Jxta_QoS structure
 * @param result A pointer to receive the result NULL-terminate string.
 * @param p The apr_pool_t structure used in the operation, from which the string will be allocated. NULL is allowed, for which
 * case the same apr_pool_t used to create the Jxta_QoS strcture will be used.
 * @return JXTA_SUCCESS with the value. JXTA_FAILED if error occurs.
 */
/* TODO: Does not make sense without a registration mechanism in place.
JXTA_DECLARE(Jxta_status) jxta_QoS_support_to_xml(Jxta_QoS * me, char ** result, apr_pool_t *p);
*/

#ifdef cplusplus
#if 0 
{
#endif
}
#endif

#endif /* JXTA_QOS_H */

/* vim: set tw=130 ts=4 sw=4 et: */

Topic JxtaCQoS . { Edit | Ref-By | Printable | Diffs r4 < r3 < r2 < r1 | More }

java.net RSS

Revision r4 - 2006-09-30 - 05:37:32 - HenryJen Parents: WebHome > JxtaC > JxtaCDocs > JxtaCSpecs	TWiki (TM) Copyright ©