<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--NewPage-->
<HTML>
<HEAD>
<!-- Generated by javadoc (build 1.6.0-google-internal) on Mon Jan 04 20:47:57 PST 2010 -->
<TITLE>
AbstractIterator (Guava Libraries 2010.01.04)
</TITLE>
<META NAME="date" CONTENT="2010-01-04">
<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../stylesheet.css" TITLE="Style">
<SCRIPT type="text/javascript">
function windowTitle()
{
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="AbstractIterator (Guava Libraries 2010.01.04)";
}
}
</SCRIPT>
<NOSCRIPT>
</NOSCRIPT>
</HEAD>
<BODY BGCOLOR="white" onload="windowTitle();">
<HR>
<!-- ========= START OF TOP NAVBAR ======= -->
<A NAME="navbar_top"><!-- --></A>
<A HREF="#skip-navbar_top" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/AbstractIterator.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
PREV CLASS
<A HREF="../../../../com/google/common/collect/ArrayListMultimap.html" title="class in com.google.common.collect"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../../../index.html?com/google/common/collect/AbstractIterator.html" target="_top"><B>FRAMES</B></A>
<A HREF="AbstractIterator.html" target="_top"><B>NO FRAMES</B></A>
<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
SUMMARY: NESTED | FIELD | <A HREF="#constructor_summary">CONSTR</A> | <A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL: FIELD | <A HREF="#constructor_detail">CONSTR</A> | <A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_top"></A>
<!-- ========= END OF TOP NAVBAR ========= -->
<HR>
<!-- ======== START OF CLASS DATA ======== -->
<H2>
<FONT SIZE="-1">
com.google.common.collect</FONT>
<BR>
Class AbstractIterator<T></H2>
<PRE>
<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang">java.lang.Object</A>
<IMG SRC="../../../../resources/inherit.gif" ALT="extended by "><A HREF="../../../../com/google/common/collect/UnmodifiableIterator.html" title="class in com.google.common.collect">com.google.common.collect.UnmodifiableIterator</A><T>
<IMG SRC="../../../../resources/inherit.gif" ALT="extended by "><B>com.google.common.collect.AbstractIterator<T></B>
</PRE>
<DL>
<DT><B>All Implemented Interfaces:</B> <DD><A HREF="http://java.sun.com/javase/6/docs/api/java/util/Iterator.html?is-external=true" title="class or interface in java.util">Iterator</A><T></DD>
</DL>
<HR>
<DL>
<DT><PRE>public abstract class <B>AbstractIterator<T></B><DT>extends <A HREF="../../../../com/google/common/collect/UnmodifiableIterator.html" title="class in com.google.common.collect">UnmodifiableIterator</A><T></DL>
</PRE>
<P>
This class provides a skeletal implementation of the <code>Iterator</code>
interface, to make this interface easier to implement for certain types of
data sources.
<p><code>Iterator</code> requires its implementations to support querying the
end-of-data status without changing the iterator's state, using the <A HREF="../../../../com/google/common/collect/AbstractIterator.html#hasNext()"><CODE>hasNext()</CODE></A> method. But many data sources, such as <A HREF="http://java.sun.com/javase/6/docs/api/java/io/Reader.html?is-external=true#read()" title="class or interface in java.io"><CODE>Reader.read()</CODE></A>), do not expose this information; the only way to
discover whether there is any data left is by trying to retrieve it. These
types of data sources are ordinarily difficult to write iterators for. But
using this class, one must implement only the <A HREF="../../../../com/google/common/collect/AbstractIterator.html#computeNext()"><CODE>computeNext()</CODE></A> method,
and invoke the <A HREF="../../../../com/google/common/collect/AbstractIterator.html#endOfData()"><CODE>endOfData()</CODE></A> method when appropriate.
<p>Another example is an iterator that skips over null elements in a backing
iterator. This could be implemented as: <pre> <code>public static Iterator<String> skipNulls(final Iterator<String> in) {
return new AbstractIterator<String>() {
protected String computeNext() {
while (in.hasNext()) {
String s = in.next();
if (s != null) {
return s;
}
}
return endOfData();
}
};
}</code></pre>
This class supports iterators that include null elements.
<P>
<P>
<DL>
<DT><B>Since:</B></DT>
<DD>2010.01.04 <b>stable</b> (imported from Google Collections Library)</DD>
<DT><B>Author:</B></DT>
<DD>Kevin Bourrillion</DD>
</DL>
<HR>
<P>
<!-- ======== CONSTRUCTOR SUMMARY ======== -->
<A NAME="constructor_summary"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Constructor Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE><B><A HREF="../../../../com/google/common/collect/AbstractIterator.html#AbstractIterator()">AbstractIterator</A></B>()</CODE>
<BR>
</TD>
</TR>
</TABLE>
<!-- ========== METHOD SUMMARY =========== -->
<A NAME="method_summary"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Method Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>protected abstract <A HREF="../../../../com/google/common/collect/AbstractIterator.html" title="type parameter in AbstractIterator">T</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../../com/google/common/collect/AbstractIterator.html#computeNext()">computeNext</A></B>()</CODE>
<BR>
Returns the next element.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>protected <A HREF="../../../../com/google/common/collect/AbstractIterator.html" title="type parameter in AbstractIterator">T</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../../com/google/common/collect/AbstractIterator.html#endOfData()">endOfData</A></B>()</CODE>
<BR>
Implementations of <code>computeNext</code> <b>must</b> invoke this method when
there are no elements left in the iteration.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE> boolean</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../../com/google/common/collect/AbstractIterator.html#hasNext()">hasNext</A></B>()</CODE>
<BR>
</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE> <A HREF="../../../../com/google/common/collect/AbstractIterator.html" title="type parameter in AbstractIterator">T</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../../com/google/common/collect/AbstractIterator.html#next()">next</A></B>()</CODE>
<BR>
</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE> <A HREF="../../../../com/google/common/collect/AbstractIterator.html" title="type parameter in AbstractIterator">T</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../../com/google/common/collect/AbstractIterator.html#peek()">peek</A></B>()</CODE>
<BR>
Returns the next element in the iteration without advancing the iteration,
according to the contract of <A HREF="../../../../com/google/common/collect/PeekingIterator.html#peek()"><CODE>PeekingIterator.peek()</CODE></A>.</TD>
</TR>
</TABLE>
<A NAME="methods_inherited_from_class_com.google.common.collect.UnmodifiableIterator"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
<TH ALIGN="left"><B>Methods inherited from class com.google.common.collect.<A HREF="../../../../com/google/common/collect/UnmodifiableIterator.html" title="class in com.google.common.collect">UnmodifiableIterator</A></B></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE><A HREF="../../../../com/google/common/collect/UnmodifiableIterator.html#remove()">remove</A></CODE></TD>
</TR>
</TABLE>
<A NAME="methods_inherited_from_class_java.lang.Object"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
<TH ALIGN="left"><B>Methods inherited from class java.lang.<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang">Object</A></B></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE><A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#clone()" title="class or interface in java.lang">clone</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#equals(java.lang.Object)" title="class or interface in java.lang">equals</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#finalize()" title="class or interface in java.lang">finalize</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#getClass()" title="class or interface in java.lang">getClass</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#hashCode()" title="class or interface in java.lang">hashCode</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#notify()" title="class or interface in java.lang">notify</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#notifyAll()" title="class or interface in java.lang">notifyAll</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#toString()" title="class or interface in java.lang">toString</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#wait()" title="class or interface in java.lang">wait</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#wait(long)" title="class or interface in java.lang">wait</A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#wait(long, int)" title="class or interface in java.lang">wait</A></CODE></TD>
</TR>
</TABLE>
<P>
<!-- ========= CONSTRUCTOR DETAIL ======== -->
<A NAME="constructor_detail"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="1"><FONT SIZE="+2">
<B>Constructor Detail</B></FONT></TH>
</TR>
</TABLE>
<A NAME="AbstractIterator()"><!-- --></A><H3>
AbstractIterator</H3>
<PRE>
public <B>AbstractIterator</B>()</PRE>
<DL>
</DL>
<!-- ============ METHOD DETAIL ========== -->
<A NAME="method_detail"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="1"><FONT SIZE="+2">
<B>Method Detail</B></FONT></TH>
</TR>
</TABLE>
<A NAME="computeNext()"><!-- --></A><H3>
computeNext</H3>
<PRE>
protected abstract <A HREF="../../../../com/google/common/collect/AbstractIterator.html" title="type parameter in AbstractIterator">T</A> <B>computeNext</B>()</PRE>
<DL>
<DD>Returns the next element. <b>Note:</b> the implementation must call <A HREF="../../../../com/google/common/collect/AbstractIterator.html#endOfData()"><CODE>endOfData()</CODE></A> when there are no elements left in the iteration. Failure to
do so could result in an infinite loop.
<p>The initial invocation of <A HREF="../../../../com/google/common/collect/AbstractIterator.html#hasNext()"><CODE>hasNext()</CODE></A> or <A HREF="../../../../com/google/common/collect/AbstractIterator.html#next()"><CODE>next()</CODE></A> calls
this method, as does the first invocation of <code>hasNext</code> or <code>next</code> following each successful call to <code>next</code>. Once the
implementation either invokes <code>endOfData</code> or throws an exception,
<code>computeNext</code> is guaranteed to never be called again.
<p>If this method throws an exception, it will propagate outward to the
<code>hasNext</code> or <code>next</code> invocation that invoked this method. Any
further attempts to use the iterator will result in an <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/IllegalStateException.html?is-external=true" title="class or interface in java.lang"><CODE>IllegalStateException</CODE></A>.
<p>The implementation of this method may not invoke the <code>hasNext</code>,
<code>next</code>, or <A HREF="../../../../com/google/common/collect/AbstractIterator.html#peek()"><CODE>peek()</CODE></A> methods on this instance; if it does, an
<code>IllegalStateException</code> will result.
<P>
<DD><DL>
<DT><B>Returns:</B><DD>the next element if there was one. If <code>endOfData</code> was called
during execution, the return value will be ignored.
<DT><B>Throws:</B>
<DD><CODE><A HREF="http://java.sun.com/javase/6/docs/api/java/lang/RuntimeException.html?is-external=true" title="class or interface in java.lang">RuntimeException</A></CODE> - if any unrecoverable error happens. This exception
will propagate outward to the <code>hasNext()</code>, <code>next()</code>, or
<code>peek()</code> invocation that invoked this method. Any further
attempts to use the iterator will result in an
<A HREF="http://java.sun.com/javase/6/docs/api/java/lang/IllegalStateException.html?is-external=true" title="class or interface in java.lang"><CODE>IllegalStateException</CODE></A>.</DL>
</DD>
</DL>
<HR>
<A NAME="endOfData()"><!-- --></A><H3>
endOfData</H3>
<PRE>
protected final <A HREF="../../../../com/google/common/collect/AbstractIterator.html" title="type parameter in AbstractIterator">T</A> <B>endOfData</B>()</PRE>
<DL>
<DD>Implementations of <code>computeNext</code> <b>must</b> invoke this method when
there are no elements left in the iteration.
<P>
<DD><DL>
<DT><B>Returns:</B><DD><code>null</code>; a convenience so your <A HREF="../../../../com/google/common/collect/AbstractIterator.html#computeNext()"><CODE>computeNext()</CODE></A>
implementation can use the simple statement <code>return endOfData();</code></DL>
</DD>
</DL>
<HR>
<A NAME="hasNext()"><!-- --></A><H3>
hasNext</H3>
<PRE>
public final boolean <B>hasNext</B>()</PRE>
<DL>
<DD><DL>
</DL>
</DD>
</DL>
<HR>
<A NAME="next()"><!-- --></A><H3>
next</H3>
<PRE>
public final <A HREF="../../../../com/google/common/collect/AbstractIterator.html" title="type parameter in AbstractIterator">T</A> <B>next</B>()</PRE>
<DL>
<DD><DL>
</DL>
</DD>
</DL>
<HR>
<A NAME="peek()"><!-- --></A><H3>
peek</H3>
<PRE>
public final <A HREF="../../../../com/google/common/collect/AbstractIterator.html" title="type parameter in AbstractIterator">T</A> <B>peek</B>()</PRE>
<DL>
<DD>Returns the next element in the iteration without advancing the iteration,
according to the contract of <A HREF="../../../../com/google/common/collect/PeekingIterator.html#peek()"><CODE>PeekingIterator.peek()</CODE></A>.
<p>Implementations of <code>AbstractIterator</code> that wish to expose this
functionality should implement <code>PeekingIterator</code>.
<P>
<DD><DL>
</DL>
</DD>
</DL>
<!-- ========= END OF CLASS DATA ========= -->
<HR>
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<A NAME="navbar_bottom"><!-- --></A>
<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/AbstractIterator.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
PREV CLASS
<A HREF="../../../../com/google/common/collect/ArrayListMultimap.html" title="class in com.google.common.collect"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../../../index.html?com/google/common/collect/AbstractIterator.html" target="_top"><B>FRAMES</B></A>
<A HREF="AbstractIterator.html" target="_top"><B>NO FRAMES</B></A>
<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
SUMMARY: NESTED | FIELD | <A HREF="#constructor_summary">CONSTR</A> | <A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL: FIELD | <A HREF="#constructor_detail">CONSTR</A> | <A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_bottom"></A>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<HR>
</BODY>
</HTML>