001    // SECTION-START[License Header]
002    /*
003     *   Copyright (c) 2009 The JOMC Project
004     *   Copyright (c) 2005 Christian Schulte <cs@jomc.org>
005     *   All rights reserved.
006     *
007     *   Redistribution and use in source and binary forms, with or without
008     *   modification, are permitted provided that the following conditions
009     *   are met:
010     *
011     *     o Redistributions of source code must retain the above copyright
012     *       notice, this list of conditions and the following disclaimer.
013     *
014     *     o Redistributions in binary form must reproduce the above copyright
015     *       notice, this list of conditions and the following disclaimer in
016     *       the documentation and/or other materials provided with the
017     *       distribution.
018     *
019     *   THIS SOFTWARE IS PROVIDED BY THE JOMC PROJECT AND CONTRIBUTORS "AS IS"
020     *   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
021     *   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
022     *   PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE JOMC PROJECT OR
023     *   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
024     *   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
025     *   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
026     *   OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
027     *   WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
028     *   OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
029     *   ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
030     *
031     *   $Id: Locator.java 652 2009-10-02 17:49:00Z schulte2005 $
032     *
033     */
034    // SECTION-END
035    package org.jomc.spi;
036    
037    import java.io.IOException;
038    import java.net.URI;
039    
040    // SECTION-START[Documentation]
041    /**
042     * Locates implementation instances.
043     * <p>This specification declares a multiplicity of {@code Many}.
044     * An application assembler may provide multiple implementations of this specification (including none).
045     * Use of class {@link org.jomc.ObjectManager ObjectManager} is supported for getting these implementations or for
046     * selecting a single implementation.<pre>
047     * Locator[] objects = (Locator[]) ObjectManagerFactory.getObjectManager().getObject( Locator.class );
048     * Locator object = ObjectManagerFactory.getObjectManager().getObject( Locator.class, "<i>implementation name</i>" );
049     * </pre>
050     * </p>
051     *
052     * <p>This specification does not apply to any scope. A new object is returned whenever requested.</p>
053     *
054     * @author <a href="mailto:cs@jomc.org">Christian Schulte</a> 1.0
055     * @version $Id: Locator.java 652 2009-10-02 17:49:00Z schulte2005 $
056     */
057    // SECTION-END
058    // SECTION-START[Annotations]
059    @javax.annotation.Generated( value = "org.jomc.tools.JavaSources",
060                                 comments = "See http://jomc.sourceforge.net/jomc/1.0-alpha-3/jomc-tools" )
061    // SECTION-END
062    public interface Locator
063    {
064        // SECTION-START[Locator]
065    
066        /**
067         * Gets an object for a given location URI.
068         *
069         * @param specification The specification class of the object to locate.
070         * @param location The location URI of the object to locate.
071         * @param <T> The type of the object.
072         *
073         * @return The object located at {@code location} or {@code null} if no object is found at {@code location}.
074         *
075         * @throws NullPointerException if {@code specification} or {@code location} is {@code null}.
076         * @throws IOException if locating the object fails.
077         */
078        <T> T getObject( Class<T> specification, URI location ) throws NullPointerException, IOException;
079    
080        // SECTION-END
081    }