001    /*
002     * file ResourceList.java
003     *
004     * Licensed Materials - Property of IBM
005     * Restricted Materials of IBM
006     * 
007     * (c) Copyright IBM Corporation 2004, 2008.  All Rights Reserved. 
008     * Note to U.S. Government Users Restricted Rights:  Use, duplication or  
009     * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp. 
010     */
011    package javax.wvcm;
012    
013    import java.util.List;
014    import java.util.NoSuchElementException;
015    
016    import javax.wvcm.WvcmException.ReasonCode;
017    
018    
019    /**
020     * A list containing {@link Resource} objects,
021     * used to perform operations on all elements of the list.
022     * A new ResourceList is created with {@link Provider#resourceList}
023     * 
024     * @since 1.0
025     */
026    public interface ResourceList<T extends Resource> extends List<T> {
027    
028        /**
029         * An iterator of the results of applying a method to
030         * each element of a ResourceList.
031         * @see java.util.Iterator
032         */
033        public interface ResponseIterator <V> {
034            /**
035             * Test whether the iteration has more elements.
036             * 
037             * @return true if the iteration has more elements.
038             * @see java.util.Iterator#hasNext
039             */
040            public boolean hasNext();
041    
042            /**
043             * Get the result of applying the method to the next element of the ResourceList.
044             * 
045             * @return if the method succeeded on the corresponding element of the ResourceList,
046             * the object returned by that method is returned; otherwise,
047             * a WvcmException is thrown. For methods that return void, next() returns null.
048             * @throws WvcmException indicates that the method failed on this element
049             * of the ResourceList.
050             * If {@link WvcmException.ReasonCode} is {@link ReasonCode#ABORTED},
051             * it does not indicate the method has failed on this element, 
052             * but instead indicates that an abort requested through {@link Feedback}
053             * has terminated the ResponseIterator.
054             * After this exception is handled, unless the reason code is {@link ReasonCode#ABORTED},
055             * further calls to hasNext() and next() are valid,
056             * and will process the remaining elements of the ResourceList.
057             * @throws NoSuchElementException iteration has no more elements.
058             * @see java.util.Iterator#next
059             */
060            public V next() throws WvcmException, NoSuchElementException;
061    
062            /**
063             * Release any resources associated with this ResponseIterator.
064             * This should be called if the client is done with this ResponseIterator
065             * even though the last call to hasNext has returned true.
066             */
067            public void release();
068        };
069    
070        /**
071         * Apply {@link Resource#doReadProperties}
072         * to each element of this ResourceList.
073         * 
074         * @param feedback the properties available in the returned proxies.
075         * @return an iterator over the results of the method on each element in this ResourceList.
076         */
077        public <V> ResponseIterator<V> doReadProperties(Feedback feedback) throws WvcmException;
078    
079        /**
080         * Apply {@link Resource#doReadProperties}
081         * to each element of this ResourceList.
082         * 
083         * @param feedback the properties available in the returned proxies.
084         * @param context additional context for the request (commonly a {@link Workspace} or {@link Stream}>
085         * @return an iterator over the results of the method on each element in this ResourceList.
086         */
087        public <V> ResponseIterator<V> doReadContextProperties(Resource context, Feedback feedback) throws WvcmException;
088    
089        /**
090         * Apply {@link Resource#doWriteProperties doWriteProperties}
091         * to each element of this ResourceList.
092         * 
093         * @param feedback the properties available in the returned proxies.
094         * @return an iterator over the results of the method on each element in this ResourceList.
095         */
096        public <V> ResponseIterator<V> doWriteProperties(Feedback feedback) throws WvcmException;
097    
098    }