001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package org.jboss.mx.persistence;
023:
024: import javax.management.AttributeList;
025:
026: import org.w3c.dom.Element;
027:
028: /**
029: * AttributePersistenceManager interface.
030: *
031: * Implementations of this interface are created by an
032: * MBean service that acts as factory and a manager
033: * for the active AttributePersistenceManager implementation
034: *
035: * The DelegatingPersistenceManager will contact the MBean
036: * to get an AttributePersistenceManager implementation.
037: *
038: * In this way, the Persistence Manager can be controlled
039: * externally as an MBean.
040: *
041: * @author <a href="mailto:dimitris@jboss.org">Dimitris Andreadis</a>
042: * @version $Revision: 57200 $
043: */
044: public interface AttributePersistenceManager {
045: // AttributePersistenceManager lifecycle -------------------------
046:
047: /**
048: * Initializes the AttributePersistenceManager using
049: * the supplied configuration element CONFIG_ELEMENT
050: * whose content will be probably different for each
051: * particular implementation.
052: *
053: * The version string is a tag that must be used by the
054: * AttributePersistenceManager implementation to make
055: * sure that data saved/loaded under different version
056: * tags are partitioned. It can be null or empty to
057: * indicate that no particular version tag is required.
058: *
059: * Once created, the configuration of the implementation
060: * object cannot change.
061: *
062: * Calling any other method before create() is executed
063: * will result in a IllegalStateException
064: *
065: * Finally, the implementation should be prepared to
066: * receive multiple concurrent calls.
067: *
068: * @param version a tag to identify the version
069: * @param config XML Element to load arbitrary config
070: * @throws Exception when any error occurs during create
071: */
072: public void create(String version, Element config) throws Exception;
073:
074: /**
075: * Returns true if the AttributePersistenceManager
076: * is "in-service" state, i.e. after create() and
077: * before destroy() has been called, false otherwise.
078: *
079: * @return true if in operational state
080: */
081: public boolean getState();
082:
083: /**
084: * Releases resources and destroys the AttributePersistenceManager.
085: * The object is unusable after destroy() has been called.
086: *
087: * Any call to any method will result to an
088: * IllegalStateException.
089: *
090: */
091: public void destroy();
092:
093: // AttributePersistenceManager Persistence -----------------------
094:
095: /**
096: * Checks if a persistened AttributeList for this particular
097: * id exists
098: *
099: * @param id the key of the image
100: * @return true if an image exists; false otherwise
101: * @throws Exception on any error
102: */
103: public boolean exists(String id) throws Exception;
104:
105: /**
106: * Uses the specified id to retrieve a previously persisted
107: * AttributeList. If no data can be found under the specified
108: * id, a null will be returned.
109: *
110: * @param id the key for retrieving the data
111: * @return the data, or null
112: * @throws Exception when an error occurs
113: */
114: public AttributeList load(String id) throws Exception;
115:
116: /**
117: * Persists an AttributeList (name/value pair list),
118: * under a specified id. The id can be used to retrieve the
119: * AttributeList later on. The actual mechanism will differ
120: * among implementations.
121: *
122: * @param id the key for retrieving the data later on, not null
123: * @param attrs the data to be persisted, not null
124: * @throws Exception when data cannot be persisted
125: */
126: public void store(String id, AttributeList attrs) throws Exception;
127:
128: /**
129: * Removes the persisted AttributeList, if exists
130: *
131: * @param id the key of the image
132: * @throws Exception when any error occurs
133: */
134: public void remove(String id) throws Exception;
135:
136: /**
137: * Removes all the persisted data stored under
138: * the configured version tag.
139: *
140: * @throws Exception when any error occurs
141: */
142: public void removeAll() throws Exception;
143:
144: /**
145: * Returns a String array with all the saved ids
146: * under the configured version tag.
147: *
148: * @return array with all persisted ids
149: * @throws Exception when any error occurs
150: */
151: public String[] listAll() throws Exception;
152:
153: }
|