/** * <p>Tells the LoopTool to watch the specified Array, Collection, Map, * Iterator, Iterable, Enumeration or POJO with an iterator() method * while the template iterates over the values within it. * </p> * <p>Under the covers, this is returning an iterable wrapper that * is also pushed onto this tool's stack. That allows this tool to * know which iterator to give later commands (i.e. stop() or skip()). * </p> * @param obj an object that Velocity's #foreach directive can iterate over * @return a {@link ManagedIterator} that this tool instance will track */ public ManagedIterator watch(Object obj) { Iterator iterator = getIterator(obj); if (iterator == null) { return null; } ManagedIterator managed = manage(iterator, null); iterators.push(managed); this.last = managed; return managed; }
/** * This is just like {@link #watch(Object)} except that it also takes * a name which is given to the {@link ManagedIterator} that is returned. * This allows the user to send stop or skip commands to that specific * iterator even when there are nested iterators within it that are being * watched. If the given name is {@code null}, then this will return * {@code null} even if the object can be watched. Provided names cannot * be {@code null}. * @param obj an object that Velocity's #foreach directive can iterate over * @param name loop name * @return a {@link ManagedIterator} that this tool instance will track * @see #watch(Object) */ public ManagedIterator watch(Object obj, String name) { // don't mess around with null names if (name == null) { return null; } Iterator iterator = getIterator(obj); if (iterator == null) { return null; } ManagedIterator managed = manage(iterator, name); iterators.push(managed); this.last = managed; return managed; }
/** * Adds another iterator to be kept in sync with the one * being managed by this instance. The values of the parallel * iterator can be retrieved from the LoopTool under the * name specified here (e.g. $loop.name or $loop.get('name')) * and are automatically updated for each iteration by this instance. * * @param iterable iterator to synchronize with * @param name loop name * @return This same {@link ManagedIterator} instance * @see SyncedIterator * @see #get(String) */ public ManagedIterator sync(Object iterable, String name) { Iterator parallel = getIterator(iterable); if (parallel == null) { return null; } if (synced == null) { synced = new HashMap<String,SyncedIterator>(); } synced.put(name, new SyncedIterator(parallel)); return this; }