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: Scope.java 540 2009-09-21 18:50:19Z schulte2005 $
032 *
033 */
034 // SECTION-END
035 package org.jomc.spi;
036
037 import java.util.Map;
038
039 // SECTION-START[Documentation]
040 /**
041 * Scope a specification applies to.
042 * <p>This specification declares a multiplicity of {@code Many}.
043 * An application assembler may provide multiple implementations of this specification (including none).
044 * Use of class {@link org.jomc.ObjectManager ObjectManager} is supported for getting these implementations or for
045 * selecting a single implementation.<pre>
046 * Scope[] objects = (Scope[]) ObjectManagerFactory.getObjectManager().getObject( Scope.class );
047 * Scope object = ObjectManagerFactory.getObjectManager().getObject( Scope.class, "<i>implementation name</i>" );
048 * </pre>
049 * </p>
050 *
051 * <p>This specification does not apply to any scope. A new object is returned whenever requested.</p>
052 *
053 * @author <a href="mailto:cs@jomc.org">Christian Schulte</a> 1.0
054 * @version $Id: Scope.java 540 2009-09-21 18:50:19Z schulte2005 $
055 */
056 // SECTION-END
057 // SECTION-START[Annotations]
058 @javax.annotation.Generated( value = "org.jomc.tools.JavaSources",
059 comments = "See http://jomc.sourceforge.net/jomc/1.0-alpha-1/jomc-tools" )
060 // SECTION-END
061 public interface Scope
062 {
063 // SECTION-START[Scope]
064
065 /**
066 * Gets the objects of the scope.
067 *
068 * @return The objects of the scope or {@code null}.
069 */
070 Map<String, Object> getObjects();
071
072 /**
073 * Gets an object from the scope.
074 *
075 * @param identifier The identifier of the object to get from the scope.
076 *
077 * @return The object identified by {@code identifier} or {@code null} if no such object exists in the scope.
078 *
079 * @throws NullPointerException if {@code identifier} is {@code null}.
080 */
081 Object getObject( String identifier ) throws NullPointerException;
082
083 /**
084 * Puts an object into the scope.
085 *
086 * @param identifier The identifier of the object to put into the scope.
087 * @param object The object to put into the scope.
088 *
089 * @return The previous object from the scope or {@code null} if there was no object in the scope.
090 *
091 * @throws NullPointerException if {@code identifier} or {@code object} is {@code null}.
092 */
093 Object putObject( String identifier, Object object ) throws NullPointerException;
094
095 /**
096 * Removes an object from the scope.
097 *
098 * @param identifier The identifier of the object to remove from the scope.
099 *
100 * @return The removed object or {@code null} if there was no object in the scope.
101 *
102 * @throws NullPointerException if {@code identifier} is {@code null}.
103 */
104 Object removeObject( String identifier ) throws NullPointerException;
105
106 // SECTION-END
107 }