Project 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. This is done because public Advertisement sub-classes are normally abstract with private sub-classes unique to the implementation.

See Also:
AdvertisementFactory, ID, Document, MimeMediaType

Constructor Summary
Advertisement()
           
 
Method Summary
 Object 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 advertisement into a document.
abstract  ID getID()
          Returns a unique ID suitable for indexing of this Advertisement.
abstract  String[] getIndexFields()
          returns an array of String fields to index the advertisement on.
 String toString()
          Return a string representaion 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 Object clone()
             throws CloneNotSupportedException

Overrides:
clone in class Object
Throws:
CloneNotSupportedException

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 advertisment. 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 Advertiement.getAdvertisementType() no matter what the real type of the advertisment.

Returns:
String 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 so as to NOT break the code of existing advertisements. In most cases you should provide your own implementation for efficeiny reasons.

Returns:
the identifying type of this Advertisement

getDocument

public abstract Document getDocument(MimeMediaType asMimeType)
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 a "pretty-print" format for human viewing and "text/xml" which provides an XML format.

Parameters:
asMimeType - MimeMediaType format representation requested
Returns:
Document the document to be used in the construction

getID

public abstract ID getID()
Returns a unique ID suitable for indexing of this 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. 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.

Since this ID is normally used for indexing, the IDs returned must be as unique as possible to avoid collisions.

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: unitialized index fields). Instead java.lang.IllegalStateException should be thrown.

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

getIndexFields

public abstract String[] getIndexFields()
returns an array of String fields to index the advertisement on.

Returns:
String [] attributes to index this advertisement on.

toString

public String toString()
Return a string representaion of this advertisement. The string will contain the advertisement formated as a UTF-8 encoded XML Document.

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

JXTA J2SE