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 751 2009-10-06 06:32:50Z 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 751 2009-10-06 06:32:50Z 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-5/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    }