001    // SECTION-START[License Header]
002    // <editor-fold defaultstate="collapsed" desc=" Generated License ">
003    /*
004     *   Copyright (c) 2009 The JOMC Project
005     *   Copyright (c) 2005 Christian Schulte <cs@jomc.org>
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 BY THE JOMC PROJECT AND CONTRIBUTORS "AS IS"
021     *   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
022     *   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
023     *   PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE JOMC PROJECT OR
024     *   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
025     *   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
026     *   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
027     *   OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
028     *   WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
029     *   OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
030     *   ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
031     *
032     *   $Id: Scope.java 1102 2009-12-07 03:01:58Z schulte2005 $
033     *
034     */
035    // </editor-fold>
036    // SECTION-END
037    package org.jomc.spi;
038    
039    import java.util.Map;
040    
041    // SECTION-START[Documentation]
042    // <editor-fold defaultstate="collapsed" desc=" Generated Documentation ">
043    /**
044     * Scope a specification applies to.
045     * <p>This specification declares a multiplicity of {@code Many}.
046     * An application assembler may provide multiple implementations of this specification (including none).
047     * Use of class {@link org.jomc.ObjectManager ObjectManager} is supported for getting these implementations or for
048     * selecting a single implementation.<pre>
049     * Scope[] objects = (Scope[]) ObjectManagerFactory.getObjectManager( getClassLoader() ).getObject( Scope.class );
050     * Scope object = ObjectManagerFactory.getObjectManager( getClassLoader() ).getObject( Scope.class, "<i>implementation name</i>" );
051     * </pre>
052     * </p>
053     *
054     * <p>This specification does not apply to any scope. A new object is returned whenever requested.</p>
055     *
056     * @author <a href="mailto:cs@jomc.org">Christian Schulte</a> 1.0
057     * @version $Id: Scope.java 1102 2009-12-07 03:01:58Z schulte2005 $
058     */
059    // </editor-fold>
060    // SECTION-END
061    // SECTION-START[Annotations]
062    // <editor-fold defaultstate="collapsed" desc=" Generated Annotations ">
063    @javax.annotation.Generated( value = "org.jomc.tools.JavaSources",
064                                 comments = "See http://jomc.sourceforge.net/jomc/1.0-alpha-11/jomc-tools" )
065    // </editor-fold>
066    // SECTION-END
067    public interface Scope
068    {
069        // SECTION-START[Scope]
070    
071        /**
072         * Gets the objects of the scope.
073         *
074         * @return The objects of the scope or {@code null}.
075         */
076        Map<String, Object> getObjects();
077    
078        /**
079         * Gets an object from the scope.
080         *
081         * @param identifier The identifier of the object to get from the scope.
082         *
083         * @return The object identified by {@code identifier} or {@code null} if no such object exists in the scope.
084         *
085         * @throws NullPointerException if {@code identifier} is {@code null}.
086         */
087        Object getObject( String identifier ) throws NullPointerException;
088    
089        /**
090         * Puts an object into the scope.
091         *
092         * @param identifier The identifier of the object to put into the scope.
093         * @param object The object to put into the scope.
094         *
095         * @return The previous object from the scope or {@code null} if there was no object in the scope.
096         *
097         * @throws NullPointerException if {@code identifier} or {@code object} is {@code null}.
098         */
099        Object putObject( String identifier, Object object ) throws NullPointerException;
100    
101        /**
102         * Removes an object from the scope.
103         *
104         * @param identifier The identifier of the object to remove from the scope.
105         *
106         * @return The removed object or {@code null} if there was no object in the scope.
107         *
108         * @throws NullPointerException if {@code identifier} is {@code null}.
109         */
110        Object removeObject( String identifier ) throws NullPointerException;
111    
112        // SECTION-END
113    }