001: /*****************************************************************************
002: * Source code information
003: * -----------------------
004: * Original author Ian Dickinson, HP Labs Bristol
005: * Author email Ian.Dickinson@hp.com
006: * Package Jena
007: * Created 8 Aug 2001
008: * Filename $RCSfile: ConcatenatedIterator.java,v $
009: * Revision $Revision: 1.13 $
010: * Release status Preview-release $State: Exp $
011: *
012: * Last modified on $Date: 2008/01/02 12:07:35 $
013: * by $Author: andy_seaborne $
014: *
015: * (c) Copyright 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
016: * (see footer for full conditions)
017: *****************************************************************************/package com.hp.hpl.jena.util.iterator;
018:
019: // Imports
020: ///////////////
021: import java.util.*;
022:
023: /**
024: * An iterator that represents the concatenation of two individual iterators.
025: * The concatenated iterator will range over the elements of the first iterator,
026: * followed by the elements of the second.
027: *
028: * @author Ian Dickinson, HP Labs (<a href="mailto:Ian.Dickinson@hp.com">email</a>)
029: * @version CVS info: $Id: ConcatenatedIterator.java,v 1.13 2008/01/02 12:07:35 andy_seaborne Exp $
030: */
031: public class ConcatenatedIterator implements Iterator {
032: // Constants
033: //////////////////////////////////
034:
035: // Static variables
036: //////////////////////////////////
037:
038: // Instance variables
039: //////////////////////////////////
040:
041: /** The first iterator */
042: private Iterator m_iter0 = null;
043:
044: /** The second iterator */
045: private Iterator m_iter1 = null;
046:
047: /** The default value for the iterator, or null if no default */
048: protected Object m_defaultValue = null;
049:
050: /** A flag to show that the default value has been returned */
051: protected boolean m_defaultValueSeen = false;
052:
053: // Constructors
054: //////////////////////////////////
055:
056: /**
057: * Construct an iterator that is the concatenation of the two
058: * given iterators. Either iterator may be a Java iterator, or a Jena
059: * node or resource iterator.
060: *
061: * @param iter0 The first iterator. Elements of this iterator will appear
062: * first in the elements read from the concatenation.
063: * @param iter1 The second iterator. Elements of this iterator will appear
064: * second in the elements read from the concatenation.
065: */
066: public ConcatenatedIterator(Iterator iter0, Iterator iter1) {
067: m_iter0 = iter0;
068: m_iter1 = iter1;
069: }
070:
071: // External signature methods
072: //////////////////////////////////
073:
074: /**
075: * Returns true if the iteration has more elements. This will be
076: * true if either of the underlying iterators has more elements.
077: *
078: * @return true if the iterator has more elements.
079: */
080: public boolean hasNext() {
081: return m_iter0.hasNext() || m_iter1.hasNext()
082: || (hasDefaultValue() && !m_defaultValueSeen);
083: }
084:
085: /**
086: * Returns the next element in the interation.
087: *
088: * @return The next object in the iteration, which will correspond to the next object in the
089: * underlying iteration, projected to the range of the projection function.
090: * @exception NoSuchElementException - iteration has no more elements.
091: */
092: public Object next() {
093: boolean next0 = m_iter0.hasNext();
094: boolean next1 = m_iter1.hasNext();
095:
096: // are there any more values from the encapsulted iterations?
097: if (next0 || next1) {
098: Object next = (next0) ? m_iter0.next() : m_iter1.next();
099:
100: // is this the default value?
101: if (hasDefaultValue() && m_defaultValue.equals(next)) {
102: m_defaultValueSeen = true;
103: }
104:
105: return next;
106: } else if (hasDefaultValue() && !m_defaultValueSeen) {
107: // return the default value for this iterator
108: m_defaultValueSeen = true;
109: return m_defaultValue;
110: } else {
111: // no more nodes, so this is an error
112: throw new NoSuchElementException(
113: "Tried to access next() element from empty concatenated iterator");
114: }
115: }
116:
117: /**
118: * Removes from the underlying collection the last element returned by
119: * the iterator (optional operation). Not supported on a concatenated
120: * iterator.
121: *
122: * @exception UnsupportedOperationException - if the remove operation is not
123: * supported by this Iterator.
124: * @exception IllegalStateException - if the next method has not yet been
125: * called, or the remove method has already been called after the
126: * last call to the next method.
127: */
128: public void remove() {
129: throw new UnsupportedOperationException(
130: "Cannot remove elements from concatenated iterator");
131: }
132:
133: /**
134: * Set the default value for this iteration, which will be a value that
135: * is guaranteed to be returned as a member of the iteration. To guarantee
136: * that the default value is only returned if it has not already been
137: * returned by the iterator, setting the default value should occur before
138: * the first call to {@link #next}.
139: *
140: * @param defaultValue The default value for the iteration, or null for
141: * there to be no default value. The default default
142: * value is null.
143: */
144: public void setDefaultValue(Object defaultValue) {
145: m_defaultValue = defaultValue;
146: }
147:
148: /**
149: * Answer true if this iteration has a default value.
150: *
151: * @return true if there is a default value
152: */
153: public boolean hasDefaultValue() {
154: return m_defaultValue != null;
155: }
156:
157: // Internal implementation methods
158: //////////////////////////////////
159:
160: //==============================================================================
161: // Inner class definitions
162: //==============================================================================
163:
164: }
165:
166: /*
167: (c) Copyright 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
168: All rights reserved.
169:
170: Redistribution and use in source and binary forms, with or without
171: modification, are permitted provided that the following conditions
172: are met:
173:
174: 1. Redistributions of source code must retain the above copyright
175: notice, this list of conditions and the following disclaimer.
176:
177: 2. Redistributions in binary form must reproduce the above copyright
178: notice, this list of conditions and the following disclaimer in the
179: documentation and/or other materials provided with the distribution.
180:
181: 3. The name of the author may not be used to endorse or promote products
182: derived from this software without specific prior written permission.
183:
184: THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
185: IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
186: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
187: IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
188: INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
189: NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
190: DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
191: THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
192: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
193: THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
194: */
|