001: /*
002: * The contents of this file are subject to the Sapient Public License
003: * Version 1.0 (the "License"); you may not use this file except in compliance
004: * with the License. You may obtain a copy of the License at
005: * http://carbon.sf.net/License.html.
006: *
007: * Software distributed under the License is distributed on an "AS IS" basis,
008: * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
009: * the specific language governing rights and limitations under the License.
010: *
011: * The Original Code is The Carbon Component Framework.
012: *
013: * The Initial Developer of the Original Code is Sapient Corporation
014: *
015: * Copyright (C) 2003 Sapient Corporation. All Rights Reserved.
016: */
017:
018: package org.sape.carbon.core.config;
019:
020: import org.jdom.Document;
021: import org.jdom.Element;
022:
023: /**
024: * <p>This interface represents the base of a bit of configuration. Instances
025: * of this class will represent live configurations in the Carbon system.
026: * </p>
027: *
028: * Copyright 2001 Sapient
029: * @since carbon 1.0
030: * @author Greg Hinkle, December 2001
031: * @version $Revision: 1.23 $($Author: dvoet $ / $Date: 2003/05/05 21:21:15 $)
032: */
033: public interface Configuration {
034:
035: /**
036: * <P>Returns the name of this configuration in the backing
037: * store, but may be null if the Configuration has not yet
038: * been saved to the backing store.
039: * </P>
040: * @return the fully-qualified path name of
041: * this Configuration in the backing store
042: */
043: String getConfigurationName();
044:
045: /**
046: * Alters the name of this configuration document
047: * @param name the new name of this configuration document
048: */
049: void setConfigurationName(String name);
050:
051: /**
052: * Returns a JDOM Document object representing the underlying data of this
053: * configuration object. Making direct changes to the data in this object
054: * may conflict with internal Carbon Core functionality.
055: * @return an {@link org.jdom.Document} object representing
056: * the full data set of this configuration
057: * document
058: */
059: Document getDataStructure();
060:
061: /**
062: * For child documents, this provides access to the specific root element
063: * for the sub-document. This is the case for attached children data such
064: * as enclosed arrays or complex-types.
065: *
066: * @return the specific root element for the sub-document
067: */
068: Element getRootElement();
069:
070: /**
071: * <P>
072: * This method makes a deep-copy of the underlying data
073: * structure for this configuration
074: * @return the newly created copy of configuration
075: */
076: Object clone();
077:
078: /**
079: * This method returns the <code>Class</code> of this component's
080: * configuration.
081: *
082: * @return Class the class object for either an interface or a class that
083: * will hold the configuration representation for a Component.
084: */
085: Class getConfigurationInterface();
086:
087: /**
088: * Is this configuration document writable or is it read-only. Shared cache
089: * instances of configuration objects should either be synchronized or
090: * marked not writable. When a configuration object is not writable, it
091: * should throw an exception if an attempt is made to modify it.
092: *
093: * @return true if this cofiguration object may be altered.
094: * @since carbon 1.1
095: */
096: boolean isConfigurationWritable();
097:
098: /**
099: * Changes this config object to a read-only, thread-safe mode. This cannot
100: * be undone for this object. To get a writable version of this object,
101: * make a clone or fetch anew from the Configuration Service
102: *
103: * @since carbon 1.1
104: */
105: void setConfigurationReadOnly();
106:
107: }
|