001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019: package org.apache.openjpa.lib.conf;
020:
021: import java.io.File;
022: import java.io.IOException;
023: import java.util.List;
024:
025: /**
026: * Hooks for deriving products with additional functionality.
027: * Parses configuration information from global, default or explictly-specified
028: * resources. All implementations of this interface will have a chance to mutate
029: * a {@link Configuration} both before and after the user-specified
030: * configuration data is loaded. The order in which the product derivations are
031: * evaluated is determined by the specificity of the derivation type.
032: *
033: * @author Abe White
034: * @author Pinaki Poddar
035: * @since 0.4.1
036: */
037: public interface ProductDerivation {
038:
039: public static final int TYPE_PRODUCT = 100;
040: public static final int TYPE_FEATURE = 1000;
041:
042: /**
043: * Return the type of derivation.
044: */
045: public int getType();
046:
047: /**
048: * Return the configuration prefix for properties of this product.
049: */
050: public String getConfigurationPrefix();
051:
052: /**
053: * Ensure that this derivation is valid. This action might consist of
054: * loading classes for the product this derivation represents to be sure
055: * they exist. Throw any throwable to indicate an invalid derivation.
056: * Invalid derivations will not be used.
057: */
058: public void validate() throws Exception;
059:
060: /**
061: * Load globals into the returned ConfigurationProvider, or return null if
062: * no globals are found.
063: */
064: public ConfigurationProvider loadGlobals(ClassLoader loader)
065: throws Exception;
066:
067: /**
068: * Load defaults into the returned ConfigurationProvider, or return null if
069: * no defaults are found.
070: */
071: public ConfigurationProvider loadDefaults(ClassLoader loader)
072: throws Exception;
073:
074: /**
075: * Load the given given resource into the returned ConfigurationProvider,
076: * or return null if it is not a resource this receiver understands.
077: * The given class loader may be null.
078: *
079: * @param anchor optional named anchor within a multiple-configuration
080: * resource
081: */
082: public ConfigurationProvider load(String resource, String anchor,
083: ClassLoader loader) throws Exception;
084:
085: /**
086: * Load given file, or return null if it is not a file this receiver
087: * understands.
088: *
089: * @param anchor optional named anchor within a multiple-configuration file
090: */
091: public ConfigurationProvider load(File file, String anchor)
092: throws Exception;
093:
094: /**
095: * Return a string identifying the default resource location for this
096: * product derivation, if one exists. If there is no default location,
097: * returns <code>null</code>.
098: *
099: * @since 1.1.0
100: */
101: public String getDefaultResourceLocation();
102:
103: /**
104: * Return a List<String> of all the anchors defined in <code>file</code>.
105: * The returned names are not fully-qualified, so must be used in
106: * conjunction with <code>file</code> in calls
107: * to {@link #load(java.io.File, String)}.
108: *
109: * Returns <code>null</code> or an empty list if no anchors could be found.
110: *
111: * @since 1.1.0
112: */
113: public List getAnchorsInFile(File file) throws IOException,
114: Exception;
115:
116: /**
117: * Return a List<String> of all the anchors defined in
118: * <code>resource</code>. The returned names are not
119: * fully-qualified, so must be used in conjunction with
120: * <code>resource</code> in calls to {@link #load(java.io.File, String)}.
121: *
122: * Returns <code>null</code> or an empty list if no anchors could be found.
123: *
124: * @since 1.1.0
125: */
126: public List getAnchorsInResource(String resource) throws Exception;
127:
128: /**
129: * Provides the instance with a callback to mutate the initial properties
130: * of the {@link ConfigurationProvider}. This is primarily to alter or
131: * add properties that determine what type of configuration is constructed,
132: * and therefore is typically used at runtime only.
133: *
134: * @return true if given ConfigurationProvider has been mutated.
135: */
136: public boolean beforeConfigurationConstruct(ConfigurationProvider cp);
137:
138: /**
139: * Provides the instance with the opportunity to mutate
140: * <code>conf</code> before the user configuration is applied.
141: *
142: * @return true if given Configuration has been mutated.
143: */
144: public boolean beforeConfigurationLoad(Configuration conf);
145:
146: /**
147: * Called after the specification has been set.
148: *
149: * @return true if given Configuration has been mutated.
150: */
151: public boolean afterSpecificationSet(Configuration conf);
152:
153: /**
154: * Called before the given Configuration is closed.
155: *
156: * @since 0.9.7
157: */
158: public void beforeConfigurationClose(Configuration conf);
159: }
|