001// SECTION-START[License Header]
002// <editor-fold defaultstate="collapsed" desc=" Generated License ">
003/*
004 *   Java Object Management and Configuration
005 *   Copyright (C) Christian Schulte, 2005-206
006 *   All rights reserved.
007 *
008 *   Redistribution and use in source and binary forms, with or without
009 *   modification, are permitted provided that the following conditions
010 *   are met:
011 *
012 *     o Redistributions of source code must retain the above copyright
013 *       notice, this list of conditions and the following disclaimer.
014 *
015 *     o Redistributions in binary form must reproduce the above copyright
016 *       notice, this list of conditions and the following disclaimer in
017 *       the documentation and/or other materials provided with the
018 *       distribution.
019 *
020 *   THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
021 *   INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
022 *   AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
023 *   THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, INDIRECT,
024 *   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
025 *   NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
026 *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
027 *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
028 *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
029 *   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
030 *
031 *   $JOMC: Locator.java 4588 2012-06-03 06:01:30Z schulte2005 $
032 *
033 */
034// </editor-fold>
035// SECTION-END
036package org.jomc.spi;
037
038import java.io.IOException;
039import java.net.URI;
040
041// SECTION-START[Documentation]
042// <editor-fold defaultstate="collapsed" desc=" Generated Documentation ">
043/**
044 * Locates objects.
045 *
046 * <dl>
047 *   <dt><b>Identifier:</b></dt><dd>org.jomc.spi.Locator</dd>
048 *   <dt><b>Multiplicity:</b></dt><dd>Many</dd>
049 *   <dt><b>Scope:</b></dt><dd>None</dd>
050 * </dl>
051 *
052 * @author <a href="mailto:schulte2005@users.sourceforge.net">Christian Schulte</a> 1.0
053 * @version 1.0
054 * @see org.jomc.ObjectManager#getObject(java.lang.Class) getObject(Locator[].class)
055 * @see org.jomc.ObjectManager#getObject(java.lang.Class,java.lang.String) getObject(Locator.class, "<i>implementation name</i>")
056 * @see org.jomc.ObjectManagerFactory
057 */
058// </editor-fold>
059// SECTION-END
060// SECTION-START[Annotations]
061// <editor-fold defaultstate="collapsed" desc=" Generated Annotations ">
062@javax.annotation.Generated( value = "org.jomc.tools.SourceFileProcessor 1.3", comments = "See http://jomc.sourceforge.net/jomc/1.3/jomc-tools-1.3" )
063// </editor-fold>
064// SECTION-END
065public interface Locator
066{
067    // SECTION-START[Locator]
068
069    /**
070     * Gets an object for a given location URI.
071     *
072     * @param specification The specification class of the object to locate.
073     * @param location The location URI of the object to locate.
074     * @param <T> The type of the object.
075     *
076     * @return The object located at {@code location} or {@code null}, if no object is found at {@code location}.
077     *
078     * @throws NullPointerException if {@code specification} or {@code location} is {@code null}.
079     * @throws IOException if locating the object fails.
080     */
081    <T> T getObject( Class<T> specification, URI location ) throws NullPointerException, IOException;
082
083    // SECTION-END
084}