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 */
011package javax.wvcm;
012
013import java.util.List;
014import java.util.NoSuchElementException;
015
016import 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 */
026public 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}