001package org.javasimon;
002
003import java.util.Iterator;
004import java.util.Map;
005
006/**
007 * Interface that declares support for arbitrary attributes that can be attached to the object (servlet style).
008 *
009 * @author <a href="mailto:virgo47@gmail.com">Richard "Virgo" Richter</a>
010 * @since 3.4
011 */
012public interface HasAttributes {
013        /**
014         * Stores an attribute in this Simon. Attributes can be used to store any custom objects.
015         *
016         * @param name a String specifying the name of the attribute
017         * @param value the Object to be stored
018         */
019        void setAttribute(String name, Object value);
020
021        /**
022         * Returns the value of the named attribute as an Object, or null if no attribute of
023         * the given name exists.
024         *
025         * @param name a String specifying the name of the attribute
026         * @return an Object containing the value of the attribute, or null if the attribute does not exist
027         */
028        Object getAttribute(String name);
029
030        /**
031         * Removes an attribute from this Simon.
032         *
033         * @param name a String specifying the name of the attribute to remove
034         */
035        void removeAttribute(String name);
036
037        /**
038         * Returns an Iterator containing the names of the attributes available to this Simon.
039         * This method returns an empty Iterator if the Simon has no attributes available to it.
040         *
041         * @return an Iterator of strings containing the names of the Simon's attributes
042         */
043        Iterator<String> getAttributeNames();
044
045        /**
046         * Returns copy of attributes as a sorted map, this can be used further for operations like {@code toString}.
047         *
048         * @return copy of attributes as a sorted map
049         * @since 3.4
050         */
051        Map<String, Object> getCopyAsSortedMap();
052
053        /**
054         * Returns the value of the named attribute typed to the specified class, or {@code null} if no attribute of
055         * the given name exists.
056         *
057         * @param name a String specifying the name of the attribute
058         * @return the value of the attribute typed to T, or {@code null} if the attribute does not exist
059         * @since 3.4
060         */
061        <T> T getAttribute(String name, Class<T> clazz);
062}