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 891 2009-11-02 03:40:00Z 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.JAXBException;
038    import javax.xml.bind.Marshaller;
039    import javax.xml.bind.Unmarshaller;
040    import javax.xml.validation.Schema;
041    import org.w3c.dom.ls.LSResourceResolver;
042    import org.xml.sax.EntityResolver;
043    import org.xml.sax.SAXException;
044    
045    /**
046     * Manages the object management and configuration model.
047     *
048     * <p><b>Resource management</b><ul>
049     * <li>{@link #getEntityResolver(java.lang.ClassLoader) }</li>
050     * <li>{@link #getResourceResolver(java.lang.ClassLoader) }</li>
051     * </ul></p>
052     *
053     * <p><b>Binding management</b><ul>
054     * <li>{@link #getContext(java.lang.ClassLoader) }</li>
055     * <li>{@link #getMarshaller(java.lang.ClassLoader) }</li>
056     * <li>{@link #getUnmarshaller(java.lang.ClassLoader) }</li>
057     * </ul></p>
058     *
059     * <p><b>Validation management</b><ul>
060     * <li>{@link #getSchema(java.lang.ClassLoader) }</li>
061     * </ul></p>
062     *
063     * @author <a href="mailto:cs@jomc.org">Christian Schulte</a>
064     * @version $Id: ModelManager.java 891 2009-11-02 03:40:00Z schulte2005 $
065     */
066    public interface ModelManager
067    {
068    
069        /**
070         * Gets a new object management and configuration entity resolver instance.
071         *
072         * @param classLoader The class loader to use for resolving entities.
073         *
074         * @return A new object management and configuration entity resolver instance resolving entities using the given
075         * class loader.
076         *
077         * @throws NullPointerException if {@code classLoader} is {@code null}.
078         */
079        EntityResolver getEntityResolver( ClassLoader classLoader ) throws NullPointerException;
080    
081        /**
082         * Gets a new object management and configuration L/S resource resolver instance.
083         *
084         * @param classLoader The class loader to use for resolving entities.
085         *
086         * @return A new object management and configuration L/S resource resolver instance resolving entities using the
087         * given class loader.
088         *
089         * @throws NullPointerException if {@code classLoader} is {@code null}.
090         */
091        LSResourceResolver getResourceResolver( ClassLoader classLoader ) throws NullPointerException;
092    
093        /**
094         * Gets a new object management and configuration JAXP schema instance.
095         *
096         * @param classLoader The class loader to use for loading schema resources.
097         *
098         * @return A new object management and configuration JAXP schema instance loaded using the given class loader.
099         *
100         * @throws NullPointerException if {@code classLoader} is {@code null}.
101         * @throws IOException if reading schema resources fails.
102         * @throws SAXException if parsing schema resources fails.
103         * @throws JAXBException if unmarshalling schema resources or creating a context fails.
104         */
105        Schema getSchema( ClassLoader classLoader ) throws NullPointerException, IOException, SAXException, JAXBException;
106    
107        /**
108         * Gets a new object management and configuration JAXB context instance.
109         *
110         * @param classLoader The class loader to create the context with.
111         *
112         * @return A new object management and configuration JAXB context instance created using the given class loader.
113         *
114         * @throws NullPointerException if {@code classLoader} is {@code null}.
115         * @throws IOException if reading schema resources fails.
116         * @throws SAXException if parsing schema resources fails.
117         * @throws JAXBException if unmarshalling schema resources or creating a context fails.
118         */
119        JAXBContext getContext( ClassLoader classLoader )
120            throws NullPointerException, IOException, SAXException, JAXBException;
121    
122        /**
123         * Gets a new object management and configuration JAXB marshaller instance.
124         *
125         * @param classLoader The class loader to create the marshaller with.
126         *
127         * @return A new object management and configuration JAXB marshaller instance created using the given class loader.
128         *
129         * @throws NullPointerException if {@code classLoader} is {@code null}.
130         * @throws IOException if reading schema resources fails.
131         * @throws SAXException if parsing schema resources fails.
132         * @throws JAXBException if unmarshalling schema resources or creating a marshaller fails.
133         */
134        Marshaller getMarshaller( ClassLoader classLoader )
135            throws NullPointerException, IOException, SAXException, JAXBException;
136    
137        /**
138         * Gets a new object management and configuration JAXB unmarshaller instance.
139         *
140         * @param classLoader The class loader to create the unmarshaller with.
141         *
142         * @return A new object management and configuration JAXB unmarshaller instance created using the given class loader.
143         *
144         * @throws NullPointerException if {@code classLoader} is {@code null}.
145         * @throws IOException if reading schema resources fails.
146         * @throws SAXException if parsing schema resources fails.
147         * @throws JAXBException if unmarshalling schema resources or creating an unmarshaller fails.
148         */
149        Unmarshaller getUnmarshaller( ClassLoader classLoader )
150            throws NullPointerException, IOException, SAXException, JAXBException;
151    
152    }