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 540 2009-09-21 18:50:19Z 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 540 2009-09-21 18:50:19Z 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-1/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 }