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    }