001 /*
002 * Copyright (c) 2009 The JOMC Project
003 * Copyright (c) 2005 Christian Schulte <cs@jomc.org>
004 * All rights reserved.
005 *
006 * Redistribution and use in source and binary forms, with or without
007 * modification, are permitted provided that the following conditions
008 * are met:
009 *
010 * o Redistributions of source code must retain the above copyright
011 * notice, this list of conditions and the following disclaimer.
012 *
013 * o Redistributions in binary form must reproduce the above copyright
014 * notice, this list of conditions and the following disclaimer in
015 * the documentation and/or other materials provided with the
016 * distribution.
017 *
018 * THIS SOFTWARE IS PROVIDED BY THE JOMC PROJECT AND CONTRIBUTORS "AS IS"
019 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
020 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
021 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE JOMC PROJECT OR
022 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
023 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
024 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
025 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
026 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
027 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
028 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
029 *
030 * $Id: ModelManager.java 509 2009-09-21 13:54:49Z schulte2005 $
031 *
032 */
033 package org.jomc.model;
034
035 import java.io.IOException;
036 import javax.xml.bind.JAXBContext;
037 import javax.xml.bind.JAXBElement;
038 import javax.xml.bind.JAXBException;
039 import javax.xml.bind.Marshaller;
040 import javax.xml.bind.Unmarshaller;
041 import javax.xml.transform.Transformer;
042 import javax.xml.transform.TransformerException;
043 import javax.xml.validation.Schema;
044 import org.w3c.dom.ls.LSResourceResolver;
045 import org.xml.sax.EntityResolver;
046 import org.xml.sax.SAXException;
047
048 /**
049 * Manages the object management and configuration model.
050 *
051 * <p><b>Entity resolution</b><ul>
052 * <li>{@link #getEntityResolver() }</li>
053 * <li>{@link #getLSResourceResolver() }</li>
054 * </ul></p>
055 *
056 * <p><b>JAXB</b><ul>
057 * <li>{@link #getContext() }</li>
058 * <li>{@link #getMarshaller(boolean, boolean) }</li>
059 * <li>{@link #getObjectFactory() }</li>
060 * <li>{@link #getUnmarshaller(boolean) }</li>
061 * </ul></p>
062 *
063 * <p><b>Validation</b><ul>
064 * <li>{@link #getSchema() }</li>
065 * <li>{@link #validateModelObject(javax.xml.bind.JAXBElement) }</li>
066 * <li>{@link #validateModules(org.jomc.model.Modules) }</li>
067 * </ul></p>
068 *
069 * <p><b>Transformation</b><ul>
070 * <li>{@link #transformModelObject(javax.xml.bind.JAXBElement, javax.xml.transform.Transformer) }</li>
071 * </ul></p>
072 *
073 * <p><b>Queries</b><ul>
074 * <li>{@link #getInstance(org.jomc.model.Modules, org.jomc.model.Implementation, java.lang.ClassLoader) }</li>
075 * <li>{@link #getInstance(org.jomc.model.Modules, org.jomc.model.Implementation, org.jomc.model.Dependency, java.lang.ClassLoader) }</li>
076 * <li>{@link #getInstance(org.jomc.model.Modules, java.lang.Object) }</li>
077 * <li>{@link #getObject(org.jomc.model.Modules, org.jomc.model.Specification, org.jomc.model.Instance) }</li>
078 * </ul></p>
079 *
080 * @author <a href="mailto:cs@jomc.org">Christian Schulte</a>
081 * @version $Id: ModelManager.java 509 2009-09-21 13:54:49Z schulte2005 $
082 */
083 public interface ModelManager
084 {
085
086 /**
087 * Gets the object management and configuration entity resolver.
088 *
089 * @return The object management and configuration entity resolver.
090 */
091 EntityResolver getEntityResolver();
092
093 /**
094 * Gets the object management and configuration L/S resolver.
095 *
096 * @return The object management and configuration L/S resolver.
097 */
098 LSResourceResolver getLSResourceResolver();
099
100 /**
101 * Gets the object management and configuration {@code ObjectFactory}.
102 *
103 * @return The object management and configuration {@code ObjectFactory}.
104 */
105 ObjectFactory getObjectFactory();
106
107 /**
108 * Gets the object management and configuration schema.
109 *
110 * @return The object management and configuration schema.
111 *
112 * @throws IOException if reading schema resources fails.
113 * @throws SAXException if parsing schema resources fails.
114 * @throws JAXBException if unmarshalling schema resources fails.
115 */
116 Schema getSchema() throws IOException, SAXException, JAXBException;
117
118 /**
119 * Gets the object management and configuration {@code JAXBContext}.
120 *
121 * @return The object management and configuration {@code JAXBContext}.
122 *
123 * @throws IOException if reading schema resources fails.
124 * @throws SAXException if parsing schema resources fails.
125 * @throws JAXBException if unmarshalling schema resources fails.
126 */
127 JAXBContext getContext() throws IOException, SAXException, JAXBException;
128
129 /**
130 * Gets an object management and configuration {@code Marshaller}.
131 *
132 * @param validating {@code true} for a marshaller with additional schema validation support enabled; {@code false}
133 * for a marshaller without additional schema validation support enabled.
134 * @param formattedOutput {@code true} for the marshaller to produce formatted output; {@code false} for the
135 * marshaller to not apply any formatting when marshalling.
136 *
137 * @return An object management and configuration {@code Marshaller}.
138 *
139 * @throws IOException if reading schema resources fails.
140 * @throws SAXException if parsing schema resources fails.
141 * @throws JAXBException if unmarshalling schema resources fails.
142 */
143 Marshaller getMarshaller( boolean validating, boolean formattedOutput )
144 throws IOException, SAXException, JAXBException;
145
146 /**
147 * Gets an object management and configuration {@code Unmarshaller}.
148 *
149 * @param validating {@code true} for an unmarshaller with additional schema validation support enabled;
150 * {@code false} for an unmarshaller without additional schema validation support enabled.
151 *
152 * @return An object management and configuration {@code Unmarshaller}.
153 *
154 * @throws IOException if reading schema resources fails.
155 * @throws SAXException if parsing schema resources fails.
156 * @throws JAXBException if unmarshalling schema resources fails.
157 */
158 Unmarshaller getUnmarshaller( boolean validating ) throws IOException, SAXException, JAXBException;
159
160 /**
161 * Validates a given model object.
162 *
163 * @param modelObject The object to validate.
164 *
165 * @throws NullPointerException if {@code modelObject} is {@code null}.
166 * @throws ModelException if {@code modelObject} is invalid.
167 * @throws IOException if reading schema resources fails.
168 * @throws SAXException if parsing schema resources fails.
169 * @throws JAXBException if unmarshalling schema resources fails.
170 */
171 void validateModelObject( JAXBElement<? extends ModelObject> modelObject )
172 throws NullPointerException, ModelException, IOException, SAXException, JAXBException;
173
174 /**
175 * Validates modules.
176 *
177 * @param modules The modules to validate.
178 *
179 * @throws NullPointerException if {@code modules} is {@code null}.
180 * @throws ModelException if {@code modules} is invalid.
181 * @throws IOException if reading schema resources fails.
182 * @throws SAXException if parsing schema resources fails.
183 * @throws JAXBException if unmarshalling schema resources fails.
184 */
185 void validateModules( Modules modules )
186 throws NullPointerException, ModelException, IOException, SAXException, JAXBException;
187
188 /**
189 * Transforms a given {@code ModelObject} with a given {@code Transformer}.
190 *
191 * @param modelObject The {@code ModelObject} to transform.
192 * @param transformer The {@code Transformer} to transform {@code modelObject} with.
193 * @param <T> The type of {@code modelObject}.
194 *
195 * @return {@code modelObject} transformed with {@code transformer}.
196 *
197 * @throws NullPointerException if {@code modelObject} or {@code transformer} is {@code null}.
198 * @throws IOException if reading schema resources fails.
199 * @throws SAXException if parsing schema resources fails.
200 * @throws JAXBException if binding fails.
201 * @throws TransformerException if the transformation fails.
202 */
203 <T extends ModelObject> T transformModelObject( JAXBElement<T> modelObject, Transformer transformer )
204 throws NullPointerException, IOException, SAXException, JAXBException, TransformerException;
205
206 /**
207 * Gets an instance of an implementation.
208 *
209 * @param modules The modules declaring the instance to get.
210 * @param implementation The implementation to get an instance of.
211 * @param classLoader The class loader of the instance to get.
212 *
213 * @return An instance of {@code implementation} or {@code null} if no instance is available.
214 *
215 * @throws NullPointerException if {@code modules}, {@code implementation} or {@code classLoader} is {@code null}.
216 */
217 Instance getInstance( Modules modules, Implementation implementation, ClassLoader classLoader )
218 throws NullPointerException;
219
220 /**
221 * Gets an instance of an implementation for a dependency.
222 *
223 * @param modules The modules declaring the instance to get.
224 * @param implementation The implementation to get an instance of.
225 * @param dependency The dependency declaring the instance to get.
226 * @param classLoader The class loader of the instance to get.
227 *
228 * @return An instance of {@code implementation} or {@code null} if no instance is available.
229 *
230 * @throws NullPointerException if {@code modules}, {@code implementation}, {@code dependency} or
231 * {@code classLoader} is {@code null}.
232 */
233 Instance getInstance( Modules modules, Implementation implementation, Dependency dependency,
234 ClassLoader classLoader )
235 throws NullPointerException;
236
237 /**
238 * Gets the instance of an object.
239 *
240 * @param modules The modules declaring the instance to get.
241 * @param object The object to get the instance of.
242 *
243 * @return The instance of {@code object} or {@code null} of nothing is known about {@code object}.
244 *
245 * @throws NullPointerException if {@code modules} or {@code object} is {@code null},
246 */
247 Instance getInstance( Modules modules, Object object )
248 throws NullPointerException;
249
250 /**
251 * Gets the object of an instance.
252 *
253 * @param modules The modules declaring the object to get.
254 * @param specification The specification specifying the object to get.
255 * @param instance The instance of the object to get.
256 *
257 * @return The object of {@code instance} or {@code null} if nothing is known about {@code instance}.
258 *
259 * @throws NullPointerException if {@code modules}, {@code specification} or {@code instance} is {@code null}.
260 * @throws InstantiationException if instantiating the object fails.
261 */
262 Object getObject( Modules modules, Specification specification, Instance instance )
263 throws NullPointerException, InstantiationException;
264
265 }