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 }