001: /*
002: * <copyright>
003: *
004: * Copyright 1997-2004 BBNT Solutions, LLC
005: * under sponsorship of the Defense Advanced Research Projects
006: * Agency (DARPA).
007: *
008: * You can redistribute this software and/or modify it under the
009: * terms of the Cougaar Open Source License as published on the
010: * Cougaar Open Source Website (www.cougaar.org).
011: *
012: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
013: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
014: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
015: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
016: * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
017: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
018: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
019: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
020: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
021: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
022: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
023: *
024: * </copyright>
025: */
026:
027: package org.cougaar.core.persist;
028:
029: import java.io.IOException;
030: import java.io.InputStream;
031: import java.io.OutputStream;
032:
033: import org.cougaar.core.adaptivity.OMCRangeList;
034: import org.cougaar.core.service.DataProtectionKey;
035:
036: /**
037: * A media-specific persistence handler for reading and writing
038: * snapshots.
039: * <p>
040: * PersistencePlugin defines the API that media-specific persistence
041: * plugins must implement. A persistence plugin defines a medium that
042: * can be used to store a series of persistence snapshots. When an
043: * agent restarts, a set of these snapshots called a rehydration set
044: * is retrieved from the persistence medium to reconstitute or
045: * "rehydrate" the previous state of the agent.
046: */
047: public interface PersistencePlugin {
048:
049: /**
050: * Initialize the plugin with PersistencePluginSupport and
051: * parameters. After initialization, the plugin should be ready to
052: * service all methods.
053: * @param pps the persistence plugin support specifies the context
054: * within which persistence is being performed.
055: * @param name the name of this plugin.
056: * @param params String parameters to configure the plugin. The
057: * parameters come from configuration information and
058: * interpretation is up to the plugin.
059: */
060: void init(PersistencePluginSupport pps, String name,
061: String[] params, boolean deleteOldPersistence)
062: throws PersistenceException;
063:
064: /**
065: * Gets the name of the PersistencePlugin. Every PersistencePlugin
066: * should have a distinct name. The name can be computed by the
067: * plugin based on its class and parameters or it can be specified
068: * as an argument in the constructor.
069: */
070: String getName();
071:
072: /**
073: * Get the average interval between persistence snapshots for this plugin
074: */
075: long getPersistenceInterval();
076:
077: void setPersistenceInterval(long newInterval);
078:
079: /**
080: * Is this persistence medium writable? Non-writable media are only
081: * used for rehydration.
082: */
083: boolean isWritable();
084:
085: void setWritable(boolean newDisable);
086:
087: /**
088: * Get the number of incremental snapshots between full snapshots.
089: */
090: int getConsolidationPeriod();
091:
092: void setConsolidationPeriod(int newPeriod);
093:
094: /**
095: * Get the number of parameters for this plugin.
096: * @return the number of parameters
097: */
098: int getParamCount();
099:
100: /**
101: * Get a specific plugin parameter.
102: * @param i the index of the desired parameter. Must be between 0
103: * (inclusive) and the value returned by
104: * {@link #getParamCount getParamCount} (exclusive).
105: * @return the value of the specified parameter.
106: */
107: String getParam(int i);
108:
109: /**
110: * Gets the names of all media-specific controls. The names of
111: * these controls must not conflict with the
112: * (@link BasePersistence#getMediaControlNames names that all
113: * media plugins have}.
114: * @return an array of the names of the controls for this media
115: * plugin.
116: */
117: String[] getControlNames();
118:
119: /**
120: * Gets the list of allowed ranges for values of the named
121: * control. Values supplied to {@link #setControl} are guaranteed
122: * to be in the specified ranges.
123: * @return the list or allowed ranges.
124: */
125: OMCRangeList getControlValues(String controlName);
126:
127: /**
128: * Set value of a particular control. Values are guaranteed to be
129: * in the ranges specified by {@link #getControlValues}
130: * @param controlName the name of the control
131: * @param newValue the new value of the control
132: */
133: void setControl(String controlName, Comparable newValue);
134:
135: /**
136: * Read the specified set of sequence numbers. These numbers
137: * should identify a complete set of persistence deltas needed to
138: * restore the specified state. A specific archive may be
139: * specified using the suffix argument.
140: * @return an array of possible rehydration sets. The timestamp of
141: * each indicates how recent each rehydration set is.
142: * @param suffix identifies which set of persistence deltas are
143: * wanted. A non-empty suffix specifies an specific, archived
144: * state. An empty suffix specifies all available sets.
145: */
146: SequenceNumbers[] readSequenceNumbers(String suffix);
147:
148: /**
149: * Cleanup old deltas as specified by cleanupNumbers. These deltas
150: * are <em>never</em> part of the current state. When archiving is
151: * enabled, the old deltas constituting an archive are not
152: * discarded.
153: * @param cleanupNumbers the numbers to be discarded (or archived).
154: */
155: void cleanupOldDeltas(SequenceNumbers cleanupNumbers);
156:
157: /**
158: * Delete old archives
159: */
160: void cleanupArchive();
161:
162: /**
163: * Open an OutputStream onto which a persistence delta can be
164: * written. The stream returned should be relatively non-blocking
165: * since it is possible for the entire agent to be blocked waiting
166: * for completion. Implementations that may block indefinitely
167: * should perform buffering as needed. Also, the OutputStream
168: * should be unique relative to other instances of the same agent
169: * @param deltaNumber the number of the delta that will be
170: * written. Numbers are never re-used so this number can be used
171: * to uniquely identify the delta.
172: * @param full indicates that the information to be written is a
173: * complete state dump and does not depend on any earlier deltas.
174: * It may be useful to distinctively mark such deltas.
175: */
176: OutputStream openOutputStream(int deltaNumber, boolean full)
177: throws IOException;
178:
179: /**
180: * Clean up after output was aborted.
181: * Called in response to an exception during the writing of the
182: * current stream.
183: * @param retainNumbers the numbers of the deltas excluding the
184: * one just written that comprise a complete rehydration set.
185: * Subsequent calls to readSequenceNumbers should return these
186: * values.
187: */
188: void abortOutputStream(SequenceNumbers retainNumbers);
189:
190: /**
191: * Clean up after closing the output stream. This method is called
192: * within a mutual exclusion semaphore such that multiple
193: * instances of the same agent cannot both be calling this or
194: * related methods. This is the opportunity to rename the output
195: * stream to its real identity.
196: * @param retainNumbers the numbers of the deltas including the
197: * one just written that comprise a complete rehydration set.
198: * Subsequent calls to readSequenceNumbers should return these
199: * values.
200: */
201: void finishOutputStream(SequenceNumbers retainNumbers, boolean full);
202:
203: /**
204: * Open an InputStream from which a persistence delta can be
205: * read.
206: * @param deltaNumber the number of the delta to be opened
207: */
208: InputStream openInputStream(int deltaNumber) throws IOException;
209:
210: /**
211: * Clean up after closing the input stream
212: * @param deltaNumber the number of the delta being closed.
213: * Provided as a convenience to the method
214: */
215: void finishInputStream(int deltaNumber);
216:
217: /**
218: * Get the connection to the database into which persistence
219: * deltas are being written for coordinated transaction
220: * management. Non-database implementations should throw an
221: * UnsupportedOperationException
222: */
223: java.sql.Connection getDatabaseConnection(Object locker)
224: throws UnsupportedOperationException;
225:
226: /**
227: * Release the connection to the database into which persistence
228: * deltas are being written for coordinated transaction
229: * management. Non-database implementations should throw an
230: * UnsupportedOperationException
231: */
232: void releaseDatabaseConnection(Object locker)
233: throws UnsupportedOperationException;
234:
235: /**
236: * Store an encrypted key for a particular delta number
237: * @param deltaNumber the number of the delta for which the key is used.
238: * @param key has the encrypted key to be stored
239: */
240: void storeDataProtectionKey(int deltaNumber, DataProtectionKey key)
241: throws IOException;
242:
243: /**
244: * Retrieve an encrypted key for a particular delta number
245: * @param deltaNumber the number of the delta for which the key is used.
246: */
247: DataProtectionKey retrieveDataProtectionKey(int deltaNumber)
248: throws IOException;
249:
250: /**
251: * Check that this agent instance still owns the persistence data
252: */
253: boolean checkOwnership() throws PersistenceException;
254:
255: /**
256: * Lock out other instances of this agent.
257: */
258: void lockOwnership() throws PersistenceException;
259:
260: /**
261: * Release the lockout of other instances of this agent.
262: */
263: void unlockOwnership() throws PersistenceException;
264: }
|