sjero.net Git - linphone/blob - p2pproxy/dependencies-src/jxse-src-2.5/api/src/net/jxta/document/Advertisement.java

   1 /*
   2  * Copyright (c) 2001-2007 Sun Microsystems, Inc.  All rights reserved.
   3  *
   4  *  The Sun Project JXTA(TM) Software License
   5  *
   6  *  Redistribution and use in source and binary forms, with or without
   7  *  modification, are permitted provided that the following conditions are met:
   8  *
   9  *  1. Redistributions of source code must retain the above copyright notice,
  10  *     this list of conditions and the following disclaimer.
  11  *
  12  *  2. Redistributions in binary form must reproduce the above copyright notice,
  13  *     this list of conditions and the following disclaimer in the documentation
  14  *     and/or other materials provided with the distribution.
  15  *
  16  *  3. The end-user documentation included with the redistribution, if any, must
  17  *     include the following acknowledgment: "This product includes software
  18  *     developed by Sun Microsystems, Inc. for JXTA(TM) technology."
  19  *     Alternately, this acknowledgment may appear in the software itself, if
  20  *     and wherever such third-party acknowledgments normally appear.
  21  *
  22  *  4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA" must
  23  *     not be used to endorse or promote products derived from this software
  24  *     without prior written permission. For written permission, please contact
  25  *     Project JXTA at http://www.jxta.org.
  26  *
  27  *  5. Products derived from this software may not be called "JXTA", nor may
  28  *     "JXTA" appear in their name, without prior written permission of Sun.
  29  *
  30  *  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
  31  *  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  32  *  FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SUN
  33  *  MICROSYSTEMS OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  34  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  35  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
  36  *  OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  37  *  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  38  *  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  39  *  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  40  *
  41  *  JXTA is a registered trademark of Sun Microsystems, Inc. in the United
  42  *  States and other countries.
  43  *
  44  *  Please see the license information page at :
  45  *  <http://www.jxta.org/project/www/license.html> for instructions on use of
  46  *  the license in source files.
  47  *
  48  *  ====================================================================
  49  *
  50  *  This software consists of voluntary contributions made by many individuals
  51  *  on behalf of Project JXTA. For more information on Project JXTA, please see
  52  *  http://www.jxta.org.
  53  *
  54  *  This license is based on the BSD license adopted by the Apache Foundation.
  55  */
  56
  57 package net.jxta.document;
  58
  59
  60 import java.lang.reflect.InvocationTargetException;
  61 import java.lang.reflect.UndeclaredThrowableException;
  62 import java.lang.reflect.Method;
  63
  64 import net.jxta.id.ID;
  65
  66
  67 /**
  68  *  Advertisements are core JXTA objects that are used to advertise Peers,
  69  *  PeerGroups, Services, Pipes or other JXTA resources. Advertisements provide
  70  *  a platform independent representation of core platform objects that can be
  71  *  exchanged between different platform implementations (Java, C, etc.).
  72  *
  73  *  <p>Each Advertisement holds a document that represents the advertisement.
  74  *  Advertisements are typically represented as a text document (XML). The
  75  *  {@link Advertisement#getDocument(MimeMediaType) getDocument(mimetype)}
  76  *  method is used to generate representations of the advertisement. Different
  77  *  representations are available via mime type selection. Typical mime types
  78  *  are "text/xml" or "text/plain" that generate textual representations for the
  79  *  Advertisements.
  80  *
  81  *  <p>Advertisements are created via {@link AdvertisementFactory} rather than
  82  *  through use of constructors. This is done because public the Advertisement
  83  *  sub-classes are typically abstract. The actual implementations are provided
  84  *  by private sub-classes.
  85  *
  86  *  @see net.jxta.document.AdvertisementFactory
  87  *  @see net.jxta.document.ExtendableAdvertisement
  88  *  @see net.jxta.id.ID
  89  *  @see net.jxta.document.Document
  90  *  @see net.jxta.document.MimeMediaType
  91  */
  92 public abstract class Advertisement {
  93
  94     /**
  95      * {@inheritDoc}
  96      */
  97     @Override
  98     public Advertisement clone() throws CloneNotSupportedException {
  99         return (Advertisement) super.clone();
 100     }
 101
 102     /**
 103      * Return a string representation of this advertisement. The string will
 104      * contain the advertisement pretty-print formatted as a UTF-8 encoded XML
 105      * Document.
 106      *
 107      * @return A String containing the advertisement.
 108      */
 109     @Override
 110     public String toString() {
 111         XMLDocument doc = (XMLDocument) getDocument(MimeMediaType.XMLUTF8);
 112
 113         // Force pretty printing
 114         doc.addAttribute("xml:space", "default");
 115
 116         return doc.toString();
 117     }
 118
 119     /**
 120      *  Returns the identifying type of this Advertisement.
 121      *
 122      *  <p/><b>Note:</b> This is a static method. It cannot be used to determine
 123      *  the runtime type of an advertisement. ie.
 124      *  </p><code><pre>
 125      *      Advertisement adv = module.getSomeAdv();
 126      *      String advType = adv.getAdvertisementType();
 127      *  </pre></code>
 128      *
 129      *  <p/><b>This is wrong and does not work the way you might expect.</b>
 130      *  This call is not polymorphic and calls
 131      *  {@code Advertisement.getAdvertisementType()} no matter what the real
 132      *  type of the advertisement.
 133      *
 134      * @return The type of advertisement.
 135      */
 136     public static String getAdvertisementType() {
 137         throw new UnsupportedOperationException(
 138                 "Advertisement : sub-class failed to override getAdvertisementType. getAdvertisementType() is static and is *not* polymorphic.");
 139     }
 140
 141     /**
 142      *  Returns the identifying type of this Advertisement. Unlike
 143      *  {@link #getAdvertisementType()} this method will return the correct
 144      *  runtime type of an Advertisement object.
 145      *  <p/>
 146      *  This implementation is provided for existing advertisements which do not
 147      *  provide their own implementation. In most cases you should provide your
 148      *  own implementation for efficiency reasons.
 149      *
 150      *  @since JXSE 2.1.1
 151      *  @return The identifying type of this Advertisement.
 152      */
 153     public String getAdvType() {
 154         try {
 155             Method getAdvertisementTypeMethod = this.getClass().getMethod("getAdvertisementType", (Class[]) null);
 156             String result = (String) getAdvertisementTypeMethod.invoke(null, (Object[]) null);
 157
 158             return result;
 159         } catch (NoSuchMethodException failed) {
 160             UnsupportedOperationException failure = new UnsupportedOperationException("Could not get Advertisement type.");
 161
 162             failure.initCause(failed);
 163             throw failure;
 164         } catch (IllegalAccessException failed) {
 165             SecurityException failure = new SecurityException("Could not get Advertisement type.");
 166
 167             failure.initCause(failed);
 168             throw failure;
 169         } catch (InvocationTargetException failed) {
 170             UndeclaredThrowableException failure = new UndeclaredThrowableException(failed, "Failed getting Advertisement type.");
 171
 172             failure.initCause(failed.getCause());
 173             throw failure;
 174         }
 175     }
 176
 177     /**
 178      *  Write this advertisement into a document of the requested type. Two
 179      *  standard document forms are defined. <code>"text/plain"</code> encodes
 180      *  the document in a "pretty-print" format for human viewing and
 181      *  <code>"text/xml"<code> which provides an XML format.
 182      *
 183      *  @param asMimeType MimeMediaType format representation requested.
 184      *  @return The {@code Advertisement} represented as a {@code Document} of
 185      *  the requested MIME Media Type.
 186      */
 187     public abstract Document getDocument(MimeMediaType asMimeType);
 188
 189     /**
 190      *  Returns an ID which identifies this {@code Advertisement} as uniquely as
 191      *  possible. This ID is typically used as the primary key for indexing of
 192      *  the Advertisement within databases.
 193      *  <p/>
 194      *  Each advertisement sub-class must choose an appropriate implementation
 195      *  which returns canonical and relatively unique ID values for it's
 196      *  instances. Since this ID is commonly used for indexing, the IDs returned
 197      *  must be as unique as possible to avoid collisions. The value for the ID
 198      *  returned can either be:
 199      *  <p/>
 200      *  <ul>
 201      *      <li>An ID which is already part of the advertisement definition
 202      *      and is relatively unique between advertisements instances. For
 203      *      example, the Peer Advertisement returns the Peer ID.</li>
 204      *
 205      *      <li>A static CodatID which is generated via some canonical process
 206      *      which will produce the same value each time and different values for
 207      *      different advertisements of the same type.</li>
 208      *
 209      *      <li>ID.nullID for advertisement types which are not readily indexed.
 210      *      </li>
 211      *  </ul>
 212      *  <p/>
 213      *  For Advertisement types which normally return non-ID.nullID values
 214      *  no ID should be returned when asked to generate an ID while the
 215      *  Advertisement is an inconsistent state (example: uninitialized index
 216      *  fields). Instead {@link java.lang.IllegalStateException} should be
 217      *  thrown.
 218      *
 219      *  @return An ID that relatively uniquely identifies this advertisement
 220      *  or {@code ID.nullID} if this advertisement is of a type that is not
 221      *  normally indexed.
 222      */
 223     public abstract ID getID();
 224
 225     /**
 226      * Returns the element names on which this advertisement should be indexed.
 227      *
 228      * @return The element names on which this advertisement should be indexed.
 229      */
 230     public abstract String[] getIndexFields();
 231 }