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 }