001: /*
002: * Copyright Aduna (http://www.aduna-software.com/) (c) 1997-2007.
003: *
004: * Licensed under the Aduna BSD-style license.
005: */
006: package org.openrdf.query;
007:
008: import java.util.Iterator;
009: import java.util.Set;
010:
011: import org.openrdf.model.Value;
012:
013: /**
014: * A BindingSet is a set of named value bindings, which is used a.o. to
015: * represent a single query solution. Values are indexed by name of the binding
016: * which typically corresponds to the names of the variables used in the
017: * projection of the orginal query.
018: */
019: public interface BindingSet extends Iterable<Binding> {
020:
021: /**
022: * Creates an iterator over the bindings in this BindingSet. This only
023: * returns bindings with non-null values. An implementation is free to return
024: * the bindings in arbitrary order.
025: */
026: public Iterator<Binding> iterator();
027:
028: /**
029: * Gets the names of the bindings in this BindingSet.
030: *
031: * @return A set of binding names.
032: */
033: public Set<String> getBindingNames();
034:
035: /**
036: * Gets the binding with the specified name from this BindingSet.
037: *
038: * @param bindingName
039: * The name of the binding.
040: * @return The binding with the specified name, or <tt>null</tt> if there
041: * is no such binding in this BindingSet.
042: */
043: public Binding getBinding(String bindingName);
044:
045: /**
046: * Checks whether this BindingSet has a binding with the specified name.
047: *
048: * @param bindingName
049: * The name of the binding.
050: * @return <tt>true</tt> if this BindingSet has a binding with the
051: * specified name, <tt>false</tt> otherwise.
052: */
053: public boolean hasBinding(String bindingName);
054:
055: /**
056: * Gets the value of the binding with the specified name from this
057: * BindingSet.
058: *
059: * @param bindingName
060: * The name of the binding.
061: * @return The value of the binding with the specified name, or <tt>null</tt>
062: * if there is no such binding in this BindingSet.
063: */
064: public Value getValue(String bindingName);
065:
066: /**
067: * Returns the number of bindings in this BindingSet.
068: *
069: * @return The number of bindings in this BindingSet.
070: */
071: public int size();
072:
073: /**
074: * Compares a BindingSet object to another object.
075: *
076: * @param o
077: * The object to compare this binding to.
078: * @return <tt>true</tt> if the other object is an instance of
079: * {@link BindingSet} and it contains the same set of bindings
080: * (disregarding order), <tt>false</tt> otherwise.
081: */
082: public boolean equals(Object o);
083:
084: /**
085: * The hash code of a binding is defined as the bit-wise XOR of the hash
086: * codes of its bindings:
087: *
088: * <pre>
089: * int hashCode = 0;
090: * for (Binding binding : this) {
091: * hashCode ˆ= binding.hashCode();
092: * }
093: * </pre>
094: *
095: * Note: the calculated hash code intentionally does not dependent on the
096: * order in which the bindings are iterated over.
097: *
098: * @return A hash code for the BindingSet.
099: */
100: public int hashCode();
101: }
|