JXTA

net.jxta.document
Class Advertisement

java.lang.Object
  extended by net.jxta.document.Advertisement
Direct Known Subclasses:
ExtendableAdvertisement

public abstract class Advertisement
extends Object

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.).

Each Advertisement holds a document that represents the advertisement. Advertisements are typically represented as a text document (XML). The 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.

Advertisements are created via AdvertisementFactory rather than through use of constructors. This is done because public the Advertisement sub-classes are typically abstract. The actual implementations are provided by private sub-classes.

See Also:
AdvertisementFactory, ExtendableAdvertisement, ID, Document, MimeMediaType

Constructor Summary
Advertisement()
           
 
Method Summary
 Advertisement clone()
          
static String getAdvertisementType()
          Returns the identifying type of this Advertisement.
 String getAdvType()
          Returns the identifying type of this Advertisement.
abstract  Document getDocument(MimeMediaType asMimeType)
          Write this advertisement into a document of the requested type.
abstract  ID getID()
          Returns an ID which identifies this Advertisement as uniquely as possible.
abstract  String[] getIndexFields()
          Returns the element names on which this advertisement should be indexed.
 String toString()
          Return a string representation of this advertisement.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Advertisement

public Advertisement()
Method Detail

clone

public Advertisement clone()
                    throws CloneNotSupportedException

Overrides:
clone in class Object
Throws:
CloneNotSupportedException

toString

public String toString()
Return a string representation of this advertisement. The string will contain the advertisement pretty-print formatted as a UTF-8 encoded XML Document.

Overrides:
toString in class Object
Returns:
A String containing the advertisement.

getAdvertisementType

public static String getAdvertisementType()
Returns the identifying type of this Advertisement.

Note: This is a static method. It cannot be used to determine the runtime type of an advertisement. ie.

      Advertisement adv = module.getSomeAdv();
      String advType = adv.getAdvertisementType();
  

This is wrong and does not work the way you might expect. This call is not polymorphic and calls Advertisement.getAdvertisementType() no matter what the real type of the advertisement.

Returns:
The type of advertisement.

getAdvType

public String getAdvType()
Returns the identifying type of this Advertisement. Unlike getAdvertisementType() this method will return the correct runtime type of an Advertisement object.

This implementation is provided for existing advertisements which do not provide their own implementation. In most cases you should provide your own implementation for efficiency reasons.

Returns:
The identifying type of this Advertisement.
Since:
JXSE 2.1.1

getDocument

public abstract Document getDocument(MimeMediaType asMimeType)
Write this advertisement into a document of the requested type. Two standard document forms are defined. "text/plain" encodes the document in a "pretty-print" format for human viewing and "text/xml" which provides an XML format.

Parameters:
asMimeType - MimeMediaType format representation requested.
Returns:
The Advertisement represented as a Document of the requested MIME Media Type.

getID

public abstract ID getID()
Returns an ID which identifies this Advertisement as uniquely as possible. This ID is typically used as the primary key for indexing of the Advertisement within databases.

Each advertisement sub-class must choose an appropriate implementation which returns canonical and relatively unique ID values for it's instances. Since this ID is commonly used for indexing, the IDs returned must be as unique as possible to avoid collisions. The value for the ID returned can either be:

  • An ID which is already part of the advertisement definition and is relatively unique between advertisements instances. For example, the Peer Advertisement returns the Peer ID.
  • A static CodatID which is generated via some canonical process which will produce the same value each time and different values for different advertisements of the same type.
  • ID.nullID for advertisement types which are not readily indexed.

For Advertisement types which normally return non-ID.nullID values no ID should be returned when asked to generate an ID while the Advertisement is an inconsistent state (example: uninitialized index fields). Instead IllegalStateException should be thrown.

Returns:
An ID that relatively uniquely identifies this advertisement or ID.nullID if this advertisement is of a type that is not normally indexed.

getIndexFields

public abstract String[] getIndexFields()
Returns the element names on which this advertisement should be indexed.

Returns:
The element names on which this advertisement should be indexed.

JXSE