001: /*---------------------------------------------------------------------------*\
002: $Id: PersistentDataClient.java 6491 2006-09-29 22:11:25Z bmc $
003: \*---------------------------------------------------------------------------*/
004:
005: package org.clapper.curn;
006:
007: import java.util.Map;
008:
009: /**
010: * <p>A <tt>PersistentDataClient</tt> is a class that wants to persist its own
011: * data in the persisted <i>curn</i> data store. A
012: * <tt>PersistentDataClient</tt> object can store and retrieve three kinds of
013: * data in the store:
014: *
015: * <ol>
016: * <li> Feed-related metadata, i.e., data that relates to a feed
017: * or channel.
018: * <li> Item-related metadata, i.e., data that relates to an item
019: * within a feed.
020: * <li> "Extra" data, i.e., data that is to be persisted but that isn't
021: * specifically related to a feed or an item.
022: * </ol>
023: *
024: * <p>Each <tt>PersistentDataClient</tt> object has its own namespace, to
025: * ensure that its variable names don't clash with other data. The namespace
026: * name is supplied by the <tt>PersistentDataClient</tt> itself; the
027: * fully-qualified class name is typically a good choice for a namespace
028: * name.</p>
029: *
030: * <p>A <tt>PersistentDataClient</tt> must register itself with the
031: * {@link DataPersister} class to activate itself; once registered, the
032: * client will be invoked automatically during the appropriate phases
033: * of execution. <b>Note:</b> Plug-in classes that implement this interface are
034: * automatically registered during plug-in discovery.</p>
035: *
036: * <p>When saving the feed meta data, <i>curn</i> polls each registered
037: * <tt>PersistentDataClient</tt> for its data.</p>
038: *
039: * @version <tt>$Revision: 6491 $</tt>
040: */
041: public interface PersistentDataClient {
042: /**
043: * Process a data item that has been read from the metadata store
044: * and is associated with a feed (or channel). This method is
045: * called when the metadata store is being loaded into memory
046: * at the beginning of a <i>curn</i> run. This method is only called
047: * for data items within this object's name space.
048: *
049: *
050: * @param name the name associated with the data item
051: * @param value the (string) value of the data
052: * @param feedData the {@link FeedCacheEntry} record for the feed
053: * @see #getMetatdataNamespace
054: * @throws CurnException on error
055: */
056: public void parseFeedMetadata(String name, String value,
057: FeedCacheEntry feedData) throws CurnException;
058:
059: /**
060: * Process a data item that has been read from the metadata store
061: * and is associated with a cached item. This method is called when
062: * the metadata store is being loaded into memory at the beginning
063: * of a <i>curn</i> run. This method is only called for data items
064: * within this object's name space.
065: *
066: * @param name the name associated with the data item
067: * @param value the (string) value of the data
068: * @param itemData The {@link FeedCacheEntry} data for the item
069: *
070: * @throws CurnException on error
071: *
072: * @see #getMetatdataNamespace
073: */
074: public void parseItemMetadata(String name, String value,
075: FeedCacheEntry itemData) throws CurnException;
076:
077: /**
078: * Process an "extra" data item that is not associated with a feed
079: * or an item. This method is called when the metadata store is
080: * being loaded into memory at the beginning of a <i>curn</i> run.
081: * This method is only called for data items within this object's name
082: * space.
083: *
084: * @param name the name of the data item
085: * @param value its value
086: *
087: * @throws CurnException on error
088: *
089: * @see #getMetatdataNamespace
090: */
091: public void parseExtraMetadata(String name, String value)
092: throws CurnException;
093:
094: /**
095: * Get the metadata that is to be saved with a particular feed or channel.
096: *
097: * @param feedData the {@link FeedCacheEntry} record for the feed
098: *
099: * @return a <tt>Map</tt> of all the name/value pairs to be associated
100: * with the feed. The names should not be qualified by the
101: * namespace; the caller will handle that. An empty or null
102: * map signifies that this object has no metadata for the feed.
103: *
104: * @throws CurnException on error
105: */
106: public Map<String, String> getMetadataForFeed(
107: FeedCacheEntry feedData) throws CurnException;
108:
109: /**
110: * Get the metadata that is to be saved with a particular item within a
111: * feed.
112: *
113: * @param itemData the {@link FeedCacheEntry} record for the item
114: * @param feedData the {@link FeedCacheEntry} record for the parent feed
115: *
116: * @return a <tt>Map</tt> of all the name/value pairs to be associated
117: * with the item. The names should not be qualified by the
118: * namespace; the caller will handle that. An empty or null
119: * map signifies that this object has no metadata for the item.
120: *
121: * @throws CurnException on error
122: */
123: public Map<String, String> getMetadataForItem(
124: FeedCacheEntry itemData, FeedCacheEntry feedData)
125: throws CurnException;
126:
127: /**
128: * Get any extra metadata (i.e., data that is not associated with a feed
129: * or an item) that is to be saved.
130: *
131: * @return a <tt>Map</tt> of all the name/value pairs to be associated
132: * with the feed. The names should not be qualified by the
133: * namespace; the caller will handle that. An empty or null
134: * map signifies that this object has no extract metadata.
135: *
136: * @throws CurnException on error
137: */
138: public Map<String, String> getExtraFeedMetadata()
139: throws CurnException;
140:
141: /**
142: * Get the namespace for this object's metadata. The namespace must
143: * be unique. Think of it as a package name for the data. Recommendation:
144: * Use the fully-qualified class name.
145: *
146: * @return the namespace
147: */
148: public String getMetatdataNamespace();
149: }
|