advertisement.java

jxme的一些相关程序,主要是手机上程序开发以及手机和计算机通信的一些程序资料,程序编译需要Ant支持

/*
 * $Id: Advertisement.java,v 1.2 2002/03/04 20:18:17 echtcherbina Exp $
 ********************
 *
 * Copyright (c) 2001 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.
 ********************
 */

package net.jxta.document;

import java.lang.IllegalStateException;
import net.jxta.id.ID;

/**
 *  Advertisements are core JXTA objects that are used to advertise Peers,
 *  PeerGroups, Services, Pipes or other JXTA resources. Advertisements provide
 *  a platform independent representation of core platform objects that can be
 *  exchanged between different platform implementations (Java, C, etc.).
 *
 *  <p>Each Advertisement holds a document that represents the advertisement.
 *  Advertisements are typically represented as a text document (XML). The
 *  {@link Advertisement#getDocument( MimeMediaType ) getDocument(mimetype)}
 *  method is used to generate representations of the advertisement. Different
 *  representations are available via mime type selection. Typical mime types
 *  are "text/xml" or "text/plain" that generate textual representations for the
 *  Advertisements.
 *
 *  <p>Advertisements are created via {@link AdvertisementFactory}. This is done
 *  because public Advertisement sub-classes are normally abstract with private
 *  sub-classes unique to the implementation.
 *
 *  @see net.jxta.document.AdvertisementFactory
 *  @see net.jxta.id.ID
 *  @see net.jxta.document.Document
 *  @see net.jxta.document.MimeMediaType
 *  @see net.jxta.peergroup.PeerGroup
 *  @see net.jxta.protocol.PeerAdvertisement
 *  @see net.jxta.protocol.PeerGroupAdvertisement
 *  @see net.jxta.protocol.PipeAdvertisement
 *
 *  @version $Revision: 1.2 $
 *  @since JXTA 1.0
 **/
public abstract class Advertisement extends Object {
    
    /**
     *  Absolute time at which this advertisement will expire.
     **/
    protected long expiration;
    
    /* inherits javadoc */
    public Object clone() throws CloneNotSupportedException {
        return super.clone();
    }
    
    /**
     *  Returns the real time at which this advertisement will expire.  The
     *  returned time absolute and is measured in milliseconds. The duration
     *  until this Advertisement expires is equal to <tt>
     *  {@link #getLocalExpirationTime() getLocalExpirationTime} -
     *  {@link java.lang.System#currentTimeMillis()}</tt>.
     *
     *  @since JXTA 1.0
     *
     * @return The absolute time in milliseconds at which this advertisement
     *  will expire.
     *
     **/
    public long getLocalExpirationTime() {
        return expiration;
    }
    
    /**
     *  Set the Expiration time for this Advertisement. Timeout is specified as
     *  and absolute time measured in milliseconds.
     *
     *  @since JXTA 1.0
     *
     *  @param timeout The absolute time in milliseconds at which this
     *  advertisement will expire.
     **/
    void setExpirationTime(long timeout) {
        this.expiration = timeout;
    }
    
    /**
     *  Set the expiration duration for this Advertisement. timeout is specified
     * as duration measured in milliseconds.
     *
     *  @since JXTA 1.0
     *
     * @param timeout  Positive number of milliseconds until this advertisement
     *  will expire. Values less than 1 are interpreted as requests for infinite
     *  timeout.
     **/
    void setExpiration(long timeout) {
        // FIXME 20011105 [e-mail] This is a temporary hack, a more obvious
        // mechanism for infinite timeout is needed. AdvertisementFactory is
        // currently passing -1 which it presumably intended to be infinite
        // timeout.
        if( timeout < 1 )
            this.expiration = Long.MAX_VALUE;
        else
            this.expiration = System.currentTimeMillis() + timeout;
    }
    
    /**
     * Returns the identifying type of this Advertisement.
     *
     * @since JXTA 1.0
     *
     * @return String the type of advertisement
     **/
    public static String getAdvertisementType() {
        throw new RuntimeException(
        "Advertisement : sub-class failed to override getAdvertisementType" );
    }
    
    /**
     *  Write advertisement into a document. asMimeType is a mime media-type
     *  specification and provides the form of the document which is being
     *  requested. Two standard document forms are defined. "text/plain" encodes
     *  the document in "pretty-print" format for human viewing and "text/xml"
     *  which provides an XML format.
     *
     *  @since JXTA 1.0
     *
     *  @param asMimeType  MimeMediaType format representation requested
     *  @return Document   the document to be used in the construction
     **/
    public abstract Document getDocument( MimeMediaType asMimeType );
    
    /**
     *  Returns a unique ID for that advertisement.
     *  The ID is supposed to be unique and is not guaranteed to be of
     *  any particular subclass of ID. Each class of advertisement is
     *  responsible for the choice of ID to return. That may be any ID
     *  already used in the advertisement for other purposes, as long
     *  as it defines the unicity of the advertisement to the satisfaction
     *  of the implementor.
     *  This ID is mainly used for indexing, therefore <b>two advertisements
     *  that return the same ID will be considered identical</b> and one them
     *  may be ignored by an indexing system.
     *
     *  @since JXTA 1.0
     *
     *  @return ID An ID that uniquely identifies the advertisement.
     **/
    public abstract ID getID( );
}