You are viewing a plain text version of this content. The canonical link for it is here.
Posted to solr-commits@lucene.apache.org by ho...@apache.org on 2006/05/28 02:41:33 UTC
svn commit: r409900 - in /incubator/solr/trunk: ./
src/java/org/apache/solr/core/ src/java/org/apache/solr/request/
src/java/org/apache/solr/search/ src/java/org/apache/solr/util/
Author: hossman
Date: Sat May 27 17:41:33 2006
New Revision: 409900
URL: http://svn.apache.org/viewvc?rev=409900&view=rev
Log:
first significant push at improving javadocs for interfaces/classes used heavily by request handler plugins
Modified:
incubator/solr/trunk/build.xml
incubator/solr/trunk/src/java/org/apache/solr/core/SolrInfoMBean.java
incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequest.java
incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequestBase.java
incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryResponse.java
incubator/solr/trunk/src/java/org/apache/solr/search/DocIterator.java
incubator/solr/trunk/src/java/org/apache/solr/search/DocList.java
incubator/solr/trunk/src/java/org/apache/solr/search/DocSet.java
incubator/solr/trunk/src/java/org/apache/solr/search/DocSlice.java
incubator/solr/trunk/src/java/org/apache/solr/util/NamedList.java
Modified: incubator/solr/trunk/build.xml
URL: http://svn.apache.org/viewvc/incubator/solr/trunk/build.xml?rev=409900&r1=409899&r2=409900&view=diff
==============================================================================
--- incubator/solr/trunk/build.xml (original)
+++ incubator/solr/trunk/build.xml Sat May 27 17:41:33 2006
@@ -26,6 +26,8 @@
<!-- Javadoc properties -->
<property name="year" value="2006" />
<property name="build.docs" value="${dest}/docs"/>
+ <property name="build.javadoc" value="${build.docs}/api"/>
+ <property name="javadoc.access" value="protected"/>
<property name="javadoc.link.java"
value="http://java.sun.com/j2se/1.5.0/docs/api/"/>
<property name="javadoc.link.junit"
@@ -33,7 +35,6 @@
<property name="javadoc.link.lucene"
value="http://lucene.apache.org/java/docs/api/"/>
<property name="javadoc.packages" value="org.apache.solr.*"/>
- <property name="build.javadoc" value="${build.docs}/api"/>
<!-- JUnit properties -->
<property name="junit.output.dir" location="${dest}/test-results"/>
@@ -98,6 +99,7 @@
version="true"
use="true"
encoding="utf8"
+ access="${javadoc.access}"
windowtitle="${Name} ${version} API"
doctitle="${Name} ${version} API"
bottom="Copyright &copy; ${year} The Apache Software Foundation"
Modified: incubator/solr/trunk/src/java/org/apache/solr/core/SolrInfoMBean.java
URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/core/SolrInfoMBean.java?rev=409900&r1=409899&r2=409900&view=diff
==============================================================================
--- incubator/solr/trunk/src/java/org/apache/solr/core/SolrInfoMBean.java (original)
+++ incubator/solr/trunk/src/java/org/apache/solr/core/SolrInfoMBean.java Sat May 27 17:41:33 2006
@@ -20,31 +20,50 @@
import org.apache.solr.util.*;
/**
+ * MBean interface for getting various ui friendly strings and URLs
+ * for use by objects which are 'plugable' to make server administration
+ * easier.
+ *
* @author ronp
* @version $Id$
*/
-
-// MBean interface for getting various ui friendly strings and URLs
-// for use by objects which are 'plugable' to make administering
-// production use easier
- // name - simple common usage name, e.g. BasicQueryHandler
- // version - simple common usage version, e.g. 2.0
- // description - simple one or two line description
- // SourceId - CVS Id, SVN Id, etc
- // Source - CVS Source, SVN Source, etc
- // docs - URL list: TWIKI, Faq, Design doc, something! :)
-
public interface SolrInfoMBean {
public enum Category { CORE, QUERYHANDLER, UPDATEHANDLER, CACHE, OTHER };
+ /**
+ * Simple common usage name, e.g. BasicQueryHandler,
+ * or fully qualified clas name.
+ */
public String getName();
+ /** Simple common usage version, e.g. 2.0 */
public String getVersion();
+ /** Simple one or two line description */
public String getDescription();
+ /** Purpose of this Class */
public Category getCategory();
+ /** CVS Id, SVN Id, etc */
public String getSourceId();
+ /** CVS Source, SVN Source, etc */
public String getSource();
+ /**
+ * Documentation URL list.
+ *
+ * <p>
+ * Suggested documentaion URLs: Homepage for sponsoring project,
+ * FAQ on class usage, Design doc for class, Wiki, bug reporting URL, etc...
+ * </p>
+ */
public URL[] getDocs();
+ /**
+ * Any statistics this instance would like to be publicly available via
+ * the Solr Administration interface.
+ *
+ * <p>
+ * Any Object type may be stored in the list, but only the
+ * <code>toString()</code> representation will be used.
+ * </p>
+ */
public NamedList getStatistics();
}
Modified: incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequest.java
URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequest.java?rev=409900&r1=409899&r2=409900&view=diff
==============================================================================
--- incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequest.java (original)
+++ incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequest.java Sat May 27 17:41:33 2006
@@ -21,40 +21,59 @@
import org.apache.solr.core.SolrCore;
/**
+ * Container for a request to execute a query.
+ *
* @author yonik
* @version $Id$
*/
public interface SolrQueryRequest {
- /** All uses of this request are finished, resources can be freed */
+ /**
+ * This method should be called when all uses of this request are
+ * finished, so that resources can be freed.
+ */
public void close();
+ /**
+ * Returns the input parameter value for the specified name
+ * @return the value, or the first value if the parameter was
+ * specified more then once; may be null.
+ */
public String getParam(String name);
+ /**
+ * Returns the input parameter values for the specified name
+ * @return the values; may be null or empty depending on implimentation
+ */
public String[] getParams(String name);
+ /**
+ * Returns the primary query string parameter of the request
+ */
public String getQueryString();
- // signifies the syntax and the handler that should be used
- // to execute this query.
+ /**
+ * Signifies the syntax and the handler that should be used
+ * to execute this query.
+ */
public String getQueryType();
- // starting position in matches to return to client
+ /** starting position in matches to return to client */
public int getStart();
- // number of matching documents to return
+ /** number of matching documents to return */
public int getLimit();
- // Get the start time of this request in milliseconds
+ /** The start time of this request in milliseconds */
public long getStartTime();
- // The index searcher associated with this request
+ /** The index searcher associated with this request */
public SolrIndexSearcher getSearcher();
- // The solr core (coordinator, etc) associated with this request
+ /** The solr core (coordinator, etc) associated with this request */
public SolrCore getCore();
- // The index schema associated with this request
+ /** The index schema associated with this request */
public IndexSchema getSchema();
/**
Modified: incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequestBase.java
URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequestBase.java?rev=409900&r1=409899&r2=409900&view=diff
==============================================================================
--- incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequestBase.java (original)
+++ incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequestBase.java Sat May 27 17:41:33 2006
@@ -23,9 +23,19 @@
import org.apache.solr.core.SolrException;
/**
-* @author yonik
-* @version $Id$
-*/
+ * Base implimentation of <code>SolrQueryRequest</code> that provides some
+ * convinience methods for accessing parameters, and manages an IndexSearcher
+ * refrence.
+ *
+ * <p>
+ * The <code>close()</code> method must be called on any instance of this
+ * class once it is no longer in use.
+ * </p>
+ *
+ *
+ * @author yonik
+ * @version $Id$
+ */
public abstract class SolrQueryRequestBase implements SolrQueryRequest {
// some standard query argument names
public static final String QUERY_NAME="q";
@@ -116,7 +126,10 @@
return core.getSchema();
}
-
+ /**
+ * Frees resources associated with this request, this method <b>must</b>
+ * be called when the object is no longer in use.
+ */
public void close() {
if (searcherHolder!=null) {
searcherHolder.decref();
Modified: incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryResponse.java
URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryResponse.java?rev=409900&r1=409899&r2=409900&view=diff
==============================================================================
--- incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryResponse.java (original)
+++ incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryResponse.java Sat May 27 17:41:33 2006
@@ -22,16 +22,44 @@
/**
* <code>SolrQueryResponse</code> is used by a query handler to return
- * the response to a query.
+ * the response to a query request.
+ *
+ * <p>
+ * <a name="returnable_data" /><b>Note On Returnable Data...</b><br/>
+ * A <code>SolrQueryResponse</code> may contain the following types of
+ * Objects generated by the <code>SolrRequestHandler</code> that processed
+ * the request.
+ * </p>
+ * <ul>
+ * <li>{@link String}</li>
+ * <li>{@link Integer}</li>
+ * <li>{@link Long}</li>
+ * <li>{@link Float}</li>
+ * <li>{@link Double}</li>
+ * <li>{@link Boolean}</li>
+ * <li>{@link Date}</li>
+ * <li>{@link org.apache.solr.search.DocList}</li>
+ * <li>{@link Map} containing any of the items in this list</li>
+ * <li>{@link NamedList} containing any of the items in this list</li>
+ * <li>{@link Collection} containing any of the items in this list</li>
+ * <li>Array containing any of the items in this list</li>
+ * <li>null</li>
+ * </ul>
+ *
* @author yonik
* @version $Id$
* @since solr 0.9
*/
-
public class SolrQueryResponse {
+ /**
+ * Container for user defined values
+ * @see #getValues
+ * @see #add
+ * @see #setAllValues
+ * @see <a href="#returnable_data">Note on Returnable Data</a>
+ */
protected NamedList values = new NamedList();
- // current holder for user defined values
protected Set<String> defaultReturnFields;
@@ -44,17 +72,23 @@
String errMsg;
***/
+ /**
+ * Gets data to be returned in this response
+ * @see <a href="#returnable_data">Note on Returnable Data</a>
+ */
public NamedList getValues() { return values; }
/**
- * Sets a list of all the named values to return.
+ * Sets data to be returned in this response
+ * @see <a href="#returnable_data">Note on Returnable Data</a>
*/
public void setAllValues(NamedList nameValuePairs) {
values=nameValuePairs;
}
/**
- * Sets the document field names of fields to return by default.
+ * Sets the document field names of fields to return by default when
+ * returning DocLists
*/
public void setReturnFields(Set<String> fields) {
defaultReturnFields=fields;
@@ -63,7 +97,8 @@
// that order can be maintained if needed?
/**
- * The document field names to return by default.
+ * Gets the document field names of fields to return by default when
+ * returning DocLists
*/
public Set<String> getReturnFields() {
return defaultReturnFields;
@@ -74,6 +109,7 @@
* Appends a named value to the list of named values to be returned.
* @param name the name of the value - may be null if unnamed
* @param val the value to add - also may be null since null is a legal value
+ * @see <a href="#returnable_data">Note on Returnable Data</a>
*/
public void add(String name, Object val) {
values.add(name,val);
@@ -94,11 +130,16 @@
return err;
}
- // Get and Set the endtime in milliseconds... used
- // to calculate query time.
+ /**
+ * The endtime of the request in milliseconds.
+ * Used to calculate query time.
+ * @see #setEndTime(long)
+ * @see #getEndTime()
+ */
protected long endtime;
- /** Time in milliseconds when the response officially finished.
+ /**
+ * Get the time in milliseconds when the response officially finished.
*/
public long getEndTime() {
if (endtime==0) {
@@ -109,11 +150,16 @@
/**
* Stop the timer for how long this query took.
+ * @see #setEndTime(long)
*/
public long setEndTime() {
return setEndTime(System.currentTimeMillis());
}
+ /**
+ * Set the in milliseconds when the response officially finished.
+ * @see #setEndTime()
+ */
public long setEndTime(long endtime) {
if (endtime!=0) {
this.endtime=endtime;
Modified: incubator/solr/trunk/src/java/org/apache/solr/search/DocIterator.java
URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/search/DocIterator.java?rev=409900&r1=409899&r2=409900&view=diff
==============================================================================
--- incubator/solr/trunk/src/java/org/apache/solr/search/DocIterator.java (original)
+++ incubator/solr/trunk/src/java/org/apache/solr/search/DocIterator.java Sat May 27 17:41:33 2006
@@ -19,19 +19,35 @@
import java.util.Iterator;
/**
+ * Simple Iterator of document Ids which may include score information.
+ *
+ * <p>
+ * The order of the documents is determined by the context in which the
+ * DocIterator instance was retrieved.
+ * </p>
+ *
* @author yonik
* @version $Id$
*/
public interface DocIterator extends Iterator<Integer> {
- public boolean hasNext();
+ // allready declared in superclass, redeclaring prevents javadoc inheritence
+ //public boolean hasNext();
/**
- * returns the next document id if hasNext()==true
+ * Returns the next document id if hasNext()==true
+ *
+ * <code>
+ * This method is functionally equivilent to <code>next()</code>
+ * @see #next()
*/
public int nextDoc();
/**
- * returns the score for the document just returned by nextDoc()
+ * Returns the score for the document just returned by <code>nextDoc()</code>
+ *
+ * <p>
+ * The value returned may be meaningless depending on the context
+ * in which the DocIterator instance was retrieved.
*/
public float score();
}
Modified: incubator/solr/trunk/src/java/org/apache/solr/search/DocList.java
URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/search/DocList.java?rev=409900&r1=409899&r2=409900&view=diff
==============================================================================
--- incubator/solr/trunk/src/java/org/apache/solr/search/DocList.java (original)
+++ incubator/solr/trunk/src/java/org/apache/solr/search/DocList.java Sat May 27 17:41:33 2006
@@ -43,7 +43,7 @@
* (as opposed to just the number collected according
* to <code>offset()</code> and <code>size()</code>).
* Hence it's always true that matches() >= size()
- * @return number of matches for the search(query&filter)
+ * @return number of matches for the search(query & any filters)
*/
public int matches();
@@ -66,6 +66,18 @@
*/
public DocList subset(int offset, int len);
+ /**
+ * Returns an interator that may be used to iterate over the documents in this DocList
+ *
+ * <p>
+ * The order of the documents returned by this iterator is based on the
+ * Sort order of the search that produced it. The Scoring information
+ * is meaningful only if <code>hasScores()</code> returns true.
+ * </p>
+ * @see #hasScores
+ */
+ public DocIterator iterator();
+
/** True if scores were retained */
public boolean hasScores();
Modified: incubator/solr/trunk/src/java/org/apache/solr/search/DocSet.java
URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/search/DocSet.java?rev=409900&r1=409899&r2=409900&view=diff
==============================================================================
--- incubator/solr/trunk/src/java/org/apache/solr/search/DocSet.java (original)
+++ incubator/solr/trunk/src/java/org/apache/solr/search/DocSet.java Sat May 27 17:41:33 2006
@@ -22,33 +22,57 @@
/**
* <code>DocSet</code> represents an unordered set of Lucene Document Ids.
+ *
* <p>
* WARNING: Any DocSet returned from SolrIndexSearcher should <b>not</b> be modified as it may have been retrieved from
* a cache and could be shared.
+ * </p>
+ *
* @author yonik
* @version $Id$
* @since solr 0.9
*/
public interface DocSet /* extends Collection<Integer> */ {
+
+ /**
+ * Adds the specified document if it is not currently in the DocSet
+ * (optional operation).
+ *
+ * @see #addUnique
+ * @throws SolrException if the implimentation does not allow modifications
+ */
public void add(int doc);
+ /**
+ * Adds a document the caller knows is not currently in the DocSet
+ * (optional operation).
+ *
+ * <p>
+ * This method may be faster then <code>add(doc)</code> in some
+ * implimentaions provided the caller is certain of the precondition.
+ * </p>
+ *
+ * @see #add
+ * @throws SolrException if the implimentation does not allow modifications
+ */
public void addUnique(int doc);
/**
- * @return The number of document ids in the set.
+ * Returns the number of documents in the set.
*/
public int size();
/**
- *
- * @param docid
- * @return
- * true if the docid is in the set
+ * Returns true if a document is in the DocSet.
*/
public boolean exists(int docid);
/**
+ * Returns an interator that may be used to iterate over all of the documents in the set.
*
- * @return an interator that may be used to iterate over all of the documents in the set.
+ * <p>
+ * The order of the documents returned by this iterator is
+ * non-deterministic, and any scoring information is meaningless
+ * </p>
*/
public DocIterator iterator();
@@ -75,7 +99,6 @@
/**
* Returns the intersection of this set with another set. Neither set is modified - a new DocSet is
* created and returned.
- * @param other
* @return a DocSet representing the intersection
*/
public DocSet intersection(DocSet other);
@@ -89,7 +112,6 @@
/**
* Returns the union of this set with another set. Neither set is modified - a new DocSet is
* created and returned.
- * @param other
* @return a DocSet representing the union
*/
public DocSet union(DocSet other);
@@ -102,7 +124,7 @@
}
-
+/** A base class that may be usefull for implimenting DocSets */
abstract class DocSetBase implements DocSet {
// Not implemented efficiently... for testing purposes only
@@ -126,16 +148,25 @@
return this.getBits().equals(other.getBits());
}
+ /**
+ * @throws SolrException Base implimentation does not allow modifications
+ */
public void add(int doc) {
throw new SolrException(500,"Unsupported Operation");
}
+ /**
+ * @throws SolrException Base implimentation does not allow modifications
+ */
public void addUnique(int doc) {
throw new SolrException(500,"Unsupported Operation");
}
- // Only the inefficient base implementation. DocSets based on
- // BitSets will return the actual BitSet without making a copy.
+ /**
+ * Inefficient base implementation.
+ *
+ * @see BitDocSet#getBits
+ */
public BitSet getBits() {
BitSet bits = new BitSet();
for (DocIterator iter = iterator(); iter.hasNext();) {
Modified: incubator/solr/trunk/src/java/org/apache/solr/search/DocSlice.java
URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/search/DocSlice.java?rev=409900&r1=409899&r2=409900&view=diff
==============================================================================
--- incubator/solr/trunk/src/java/org/apache/solr/search/DocSlice.java (original)
+++ incubator/solr/trunk/src/java/org/apache/solr/search/DocSlice.java Sat May 27 17:41:33 2006
@@ -33,11 +33,12 @@
final float maxScore;
/**
+ * Primary constructer for a DocSlice instance.
*
* @param offset starting offset for this range of docs
* @param len length of results
* @param docs array of docids starting at position 0
- * @param scores
+ * @param scores array of scores that corrisponds to docs, may be null
* @param matches total number of matches for the query
*/
public DocSlice(int offset, int len, int[] docs, float[] scores, int matches, float maxScore) {
Modified: incubator/solr/trunk/src/java/org/apache/solr/util/NamedList.java
URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/util/NamedList.java?rev=409900&r1=409899&r2=409900&view=diff
==============================================================================
--- incubator/solr/trunk/src/java/org/apache/solr/util/NamedList.java (original)
+++ incubator/solr/trunk/src/java/org/apache/solr/util/NamedList.java Sat May 27 17:41:33 2006
@@ -20,56 +20,100 @@
import java.io.Serializable;
/**
+ * A simple container class for modeling an ordered list of name/value pairs.
+ *
+ * <p>
+ * Unlike Maps:
+ * </p>
+ * <ul>
+ * <li>Names may be repeated</li>
+ * <li>Order of elements is maintained</li>
+ * <li>Elements may be accessed by numeric index</li>
+ * <li>Names and Values can both be null</li>
+ * </ul>
+ *
+ * <p>
+ * :TODO: In the future, it would be nice if this extended Map or Collection,
+ * had iterators, used java5 generics, had a faster lookup for
+ * large lists, etc...
+ * It could also have an interface, and multiple implementations.
+ * One might have indexed lookup, one might not.
+ * </p>
+ *
* @author yonik
* @version $Id$
*/
-//
-// A quick hack of a class to represent a list of name-value pairs.
-// Unlike a map, order is maintained, and names may
-// be repeated. Names and values may be null.
-//
-// In the future, it would be nice if this extended Map or Collection,
-// had iterators, used java5 generics, had a faster lookup for
-// large lists, etc...
-// It could also have an interface, and multiple implementations.
-// One might have indexed lookup, one might not.
-//
public class NamedList implements Cloneable, Serializable {
protected final List nvPairs;
+ /** Creates an empty instance */
public NamedList() {
nvPairs = new ArrayList();
}
+ /**
+ * Creates an instance backed by an explicitly specified list of
+ * pairwise names/values.
+ *
+ * @param nameValuePairs underlying List which should be used to impliment a NamedList; modifying this List will affect the NamedList.
+ */
public NamedList(List nameValuePairs) {
nvPairs=nameValuePairs;
}
+ /** The total number of name/value pairs */
public int size() {
return nvPairs.size() >> 1;
}
+ /**
+ * The name of the pair at the specified List index
+ *
+ * @return null if no name exists
+ */
public String getName(int idx) {
return (String)nvPairs.get(idx << 1);
}
+ /**
+ * The value of the pair at the specified List index
+ *
+ * @return may be null
+ */
public Object getVal(int idx) {
return nvPairs.get((idx << 1) + 1);
}
-
+
+ /**
+ * Adds a name/value pair to the end of the list.
+ */
public void add(String name, Object val) {
nvPairs.add(name);
nvPairs.add(val);
}
+ /**
+ * Modifies the name of the pair at the specified index.
+ */
public void setName(int idx, String name) {
nvPairs.set(idx<<1, name);
}
+ /**
+ * Modifies the value of the pair at the specified index.
+ */
public void setVal(int idx, Object val) {
nvPairs.set((idx<<1)+1, val);
}
+ /**
+ * Scans the list sequentially begining at the specified index and
+ * returns the index of the first pair with the specified name.
+ *
+ * @param name name to look for, may be null
+ * @param start index to begin searching from
+ * @return The index of the first matching pair, -1 if no match
+ */
public int indexOf(String name, int start) {
int sz = size();
for (int i=start; i<sz; i++) {
@@ -83,15 +127,25 @@
return -1;
}
-
- // gets the value for the first specified name. returns null if not
- // found or if the value stored was null.
+ /**
+ * Gets the value for the first instance of the specified name
+ * found.
+ *
+ * @return null if not found or if the value stored was null.
+ * @see #indexOf
+ * @see #get(String,int)
+ */
public Object get(String name) {
return get(name,0);
}
- // gets the value for the first specified name starting start.
- // returns null if not found or if the value stored was null.
+ /**
+ * Gets the value for the first instance of the specified name
+ * found starting at the specified index.
+ *
+ * @return null if not found or if the value stored was null.
+ * @see #indexOf
+ */
public Object get(String name, int start) {
int sz = size();
for (int i=start; i<sz; i++) {
@@ -120,7 +174,9 @@
return sb.toString();
}
-
+ /**
+ * Iterates over the Map and sequentially adds it's key/value pairs
+ */
public boolean addAll(Map args) {
Set eset = args.entrySet();
Iterator iter = eset.iterator();
@@ -132,7 +188,7 @@
}
/**
- * Makes a *shallow copy* of the named list.
+ * Makes a <i>shallow copy</i> of the named list.
*/
public NamedList clone() {
ArrayList newList = new ArrayList(nvPairs.size());
Re: svn commit: r409900 - in /incubator/solr/trunk: ./ src/java/org/apache/solr/core/ src/java/org/apache/solr/request/ src/java/org/apache/solr/search/ src/java/org/apache/solr/util/
Posted by Yonik Seeley <ys...@gmail.com>.
On 5/27/06, Chris Hostetter <ho...@fucit.org> wrote:
> I'd apprecaite it if as many people as possible could review the javadocs
> for these classes and let me know if anything looks "wrong" (by which i
> mean genuine mistakes in the description of functionality, grammatical
> errors, typos, ... the usual things I'm prone to).
Thanks Hoss, Content looks good. I just checked in corrections for
the other stuff ;-)
-Yonik
Re: svn commit: r409900 - in /incubator/solr/trunk: ./
src/java/org/apache/solr/core/ src/java/org/apache/solr/request/
src/java/org/apache/solr/search/ src/java/org/apache/solr/util/
Posted by Chris Hostetter <ho...@fucit.org>.
I'd apprecaite it if as many people as possible could review the javadocs
for these classes and let me know if anything looks "wrong" (by which i
mean genuine mistakes in the description of functionality, grammatical
errors, typos, ... the usual things I'm prone to).
: Date: Sun, 28 May 2006 00:41:33 -0000
: From: hossman@apache.org
: Reply-To: solr-dev@lucene.apache.org
: To: solr-commits@lucene.apache.org
: Subject: svn commit: r409900 - in /incubator/solr/trunk: ./
: src/java/org/apache/solr/core/ src/java/org/apache/solr/request/
: src/java/org/apache/solr/search/ src/java/org/apache/solr/util/
:
: Author: hossman
: Date: Sat May 27 17:41:33 2006
: New Revision: 409900
:
: URL: http://svn.apache.org/viewvc?rev=409900&view=rev
: Log:
: first significant push at improving javadocs for interfaces/classes used heavily by request handler plugins
:
: Modified:
: incubator/solr/trunk/build.xml
: incubator/solr/trunk/src/java/org/apache/solr/core/SolrInfoMBean.java
: incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequest.java
: incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequestBase.java
: incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryResponse.java
: incubator/solr/trunk/src/java/org/apache/solr/search/DocIterator.java
: incubator/solr/trunk/src/java/org/apache/solr/search/DocList.java
: incubator/solr/trunk/src/java/org/apache/solr/search/DocSet.java
: incubator/solr/trunk/src/java/org/apache/solr/search/DocSlice.java
: incubator/solr/trunk/src/java/org/apache/solr/util/NamedList.java
:
: Modified: incubator/solr/trunk/build.xml
: URL: http://svn.apache.org/viewvc/incubator/solr/trunk/build.xml?rev=409900&r1=409899&r2=409900&view=diff
: ==============================================================================
: --- incubator/solr/trunk/build.xml (original)
: +++ incubator/solr/trunk/build.xml Sat May 27 17:41:33 2006
: @@ -26,6 +26,8 @@
: <!-- Javadoc properties -->
: <property name="year" value="2006" />
: <property name="build.docs" value="${dest}/docs"/>
: + <property name="build.javadoc" value="${build.docs}/api"/>
: + <property name="javadoc.access" value="protected"/>
: <property name="javadoc.link.java"
: value="http://java.sun.com/j2se/1.5.0/docs/api/"/>
: <property name="javadoc.link.junit"
: @@ -33,7 +35,6 @@
: <property name="javadoc.link.lucene"
: value="http://lucene.apache.org/java/docs/api/"/>
: <property name="javadoc.packages" value="org.apache.solr.*"/>
: - <property name="build.javadoc" value="${build.docs}/api"/>
:
: <!-- JUnit properties -->
: <property name="junit.output.dir" location="${dest}/test-results"/>
: @@ -98,6 +99,7 @@
: version="true"
: use="true"
: encoding="utf8"
: + access="${javadoc.access}"
: windowtitle="${Name} ${version} API"
: doctitle="${Name} ${version} API"
: bottom="Copyright &copy; ${year} The Apache Software Foundation"
:
: Modified: incubator/solr/trunk/src/java/org/apache/solr/core/SolrInfoMBean.java
: URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/core/SolrInfoMBean.java?rev=409900&r1=409899&r2=409900&view=diff
: ==============================================================================
: --- incubator/solr/trunk/src/java/org/apache/solr/core/SolrInfoMBean.java (original)
: +++ incubator/solr/trunk/src/java/org/apache/solr/core/SolrInfoMBean.java Sat May 27 17:41:33 2006
: @@ -20,31 +20,50 @@
: import org.apache.solr.util.*;
:
: /**
: + * MBean interface for getting various ui friendly strings and URLs
: + * for use by objects which are 'plugable' to make server administration
: + * easier.
: + *
: * @author ronp
: * @version $Id$
: */
: -
: -// MBean interface for getting various ui friendly strings and URLs
: -// for use by objects which are 'plugable' to make administering
: -// production use easier
: - // name - simple common usage name, e.g. BasicQueryHandler
: - // version - simple common usage version, e.g. 2.0
: - // description - simple one or two line description
: - // SourceId - CVS Id, SVN Id, etc
: - // Source - CVS Source, SVN Source, etc
: - // docs - URL list: TWIKI, Faq, Design doc, something! :)
: -
: public interface SolrInfoMBean {
:
: public enum Category { CORE, QUERYHANDLER, UPDATEHANDLER, CACHE, OTHER };
:
: + /**
: + * Simple common usage name, e.g. BasicQueryHandler,
: + * or fully qualified clas name.
: + */
: public String getName();
: + /** Simple common usage version, e.g. 2.0 */
: public String getVersion();
: + /** Simple one or two line description */
: public String getDescription();
: + /** Purpose of this Class */
: public Category getCategory();
: + /** CVS Id, SVN Id, etc */
: public String getSourceId();
: + /** CVS Source, SVN Source, etc */
: public String getSource();
: + /**
: + * Documentation URL list.
: + *
: + * <p>
: + * Suggested documentaion URLs: Homepage for sponsoring project,
: + * FAQ on class usage, Design doc for class, Wiki, bug reporting URL, etc...
: + * </p>
: + */
: public URL[] getDocs();
: + /**
: + * Any statistics this instance would like to be publicly available via
: + * the Solr Administration interface.
: + *
: + * <p>
: + * Any Object type may be stored in the list, but only the
: + * <code>toString()</code> representation will be used.
: + * </p>
: + */
: public NamedList getStatistics();
:
: }
:
: Modified: incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequest.java
: URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequest.java?rev=409900&r1=409899&r2=409900&view=diff
: ==============================================================================
: --- incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequest.java (original)
: +++ incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequest.java Sat May 27 17:41:33 2006
: @@ -21,40 +21,59 @@
: import org.apache.solr.core.SolrCore;
:
: /**
: + * Container for a request to execute a query.
: + *
: * @author yonik
: * @version $Id$
: */
: public interface SolrQueryRequest {
:
: - /** All uses of this request are finished, resources can be freed */
: + /**
: + * This method should be called when all uses of this request are
: + * finished, so that resources can be freed.
: + */
: public void close();
:
: + /**
: + * Returns the input parameter value for the specified name
: + * @return the value, or the first value if the parameter was
: + * specified more then once; may be null.
: + */
: public String getParam(String name);
:
: + /**
: + * Returns the input parameter values for the specified name
: + * @return the values; may be null or empty depending on implimentation
: + */
: public String[] getParams(String name);
:
: + /**
: + * Returns the primary query string parameter of the request
: + */
: public String getQueryString();
:
: - // signifies the syntax and the handler that should be used
: - // to execute this query.
: + /**
: + * Signifies the syntax and the handler that should be used
: + * to execute this query.
: + */
: public String getQueryType();
:
: - // starting position in matches to return to client
: + /** starting position in matches to return to client */
: public int getStart();
:
: - // number of matching documents to return
: + /** number of matching documents to return */
: public int getLimit();
:
: - // Get the start time of this request in milliseconds
: + /** The start time of this request in milliseconds */
: public long getStartTime();
:
: - // The index searcher associated with this request
: + /** The index searcher associated with this request */
: public SolrIndexSearcher getSearcher();
:
: - // The solr core (coordinator, etc) associated with this request
: + /** The solr core (coordinator, etc) associated with this request */
: public SolrCore getCore();
:
: - // The index schema associated with this request
: + /** The index schema associated with this request */
: public IndexSchema getSchema();
:
: /**
:
: Modified: incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequestBase.java
: URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequestBase.java?rev=409900&r1=409899&r2=409900&view=diff
: ==============================================================================
: --- incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequestBase.java (original)
: +++ incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryRequestBase.java Sat May 27 17:41:33 2006
: @@ -23,9 +23,19 @@
: import org.apache.solr.core.SolrException;
:
: /**
: -* @author yonik
: -* @version $Id$
: -*/
: + * Base implimentation of <code>SolrQueryRequest</code> that provides some
: + * convinience methods for accessing parameters, and manages an IndexSearcher
: + * refrence.
: + *
: + * <p>
: + * The <code>close()</code> method must be called on any instance of this
: + * class once it is no longer in use.
: + * </p>
: + *
: + *
: + * @author yonik
: + * @version $Id$
: + */
: public abstract class SolrQueryRequestBase implements SolrQueryRequest {
: // some standard query argument names
: public static final String QUERY_NAME="q";
: @@ -116,7 +126,10 @@
: return core.getSchema();
: }
:
: -
: + /**
: + * Frees resources associated with this request, this method <b>must</b>
: + * be called when the object is no longer in use.
: + */
: public void close() {
: if (searcherHolder!=null) {
: searcherHolder.decref();
:
: Modified: incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryResponse.java
: URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryResponse.java?rev=409900&r1=409899&r2=409900&view=diff
: ==============================================================================
: --- incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryResponse.java (original)
: +++ incubator/solr/trunk/src/java/org/apache/solr/request/SolrQueryResponse.java Sat May 27 17:41:33 2006
: @@ -22,16 +22,44 @@
:
: /**
: * <code>SolrQueryResponse</code> is used by a query handler to return
: - * the response to a query.
: + * the response to a query request.
: + *
: + * <p>
: + * <a name="returnable_data" /><b>Note On Returnable Data...</b><br/>
: + * A <code>SolrQueryResponse</code> may contain the following types of
: + * Objects generated by the <code>SolrRequestHandler</code> that processed
: + * the request.
: + * </p>
: + * <ul>
: + * <li>{@link String}</li>
: + * <li>{@link Integer}</li>
: + * <li>{@link Long}</li>
: + * <li>{@link Float}</li>
: + * <li>{@link Double}</li>
: + * <li>{@link Boolean}</li>
: + * <li>{@link Date}</li>
: + * <li>{@link org.apache.solr.search.DocList}</li>
: + * <li>{@link Map} containing any of the items in this list</li>
: + * <li>{@link NamedList} containing any of the items in this list</li>
: + * <li>{@link Collection} containing any of the items in this list</li>
: + * <li>Array containing any of the items in this list</li>
: + * <li>null</li>
: + * </ul>
: + *
: * @author yonik
: * @version $Id$
: * @since solr 0.9
: */
: -
: public class SolrQueryResponse {
:
: + /**
: + * Container for user defined values
: + * @see #getValues
: + * @see #add
: + * @see #setAllValues
: + * @see <a href="#returnable_data">Note on Returnable Data</a>
: + */
: protected NamedList values = new NamedList();
: - // current holder for user defined values
:
: protected Set<String> defaultReturnFields;
:
: @@ -44,17 +72,23 @@
: String errMsg;
: ***/
:
: + /**
: + * Gets data to be returned in this response
: + * @see <a href="#returnable_data">Note on Returnable Data</a>
: + */
: public NamedList getValues() { return values; }
:
: /**
: - * Sets a list of all the named values to return.
: + * Sets data to be returned in this response
: + * @see <a href="#returnable_data">Note on Returnable Data</a>
: */
: public void setAllValues(NamedList nameValuePairs) {
: values=nameValuePairs;
: }
:
: /**
: - * Sets the document field names of fields to return by default.
: + * Sets the document field names of fields to return by default when
: + * returning DocLists
: */
: public void setReturnFields(Set<String> fields) {
: defaultReturnFields=fields;
: @@ -63,7 +97,8 @@
: // that order can be maintained if needed?
:
: /**
: - * The document field names to return by default.
: + * Gets the document field names of fields to return by default when
: + * returning DocLists
: */
: public Set<String> getReturnFields() {
: return defaultReturnFields;
: @@ -74,6 +109,7 @@
: * Appends a named value to the list of named values to be returned.
: * @param name the name of the value - may be null if unnamed
: * @param val the value to add - also may be null since null is a legal value
: + * @see <a href="#returnable_data">Note on Returnable Data</a>
: */
: public void add(String name, Object val) {
: values.add(name,val);
: @@ -94,11 +130,16 @@
: return err;
: }
:
: - // Get and Set the endtime in milliseconds... used
: - // to calculate query time.
: + /**
: + * The endtime of the request in milliseconds.
: + * Used to calculate query time.
: + * @see #setEndTime(long)
: + * @see #getEndTime()
: + */
: protected long endtime;
:
: - /** Time in milliseconds when the response officially finished.
: + /**
: + * Get the time in milliseconds when the response officially finished.
: */
: public long getEndTime() {
: if (endtime==0) {
: @@ -109,11 +150,16 @@
:
: /**
: * Stop the timer for how long this query took.
: + * @see #setEndTime(long)
: */
: public long setEndTime() {
: return setEndTime(System.currentTimeMillis());
: }
:
: + /**
: + * Set the in milliseconds when the response officially finished.
: + * @see #setEndTime()
: + */
: public long setEndTime(long endtime) {
: if (endtime!=0) {
: this.endtime=endtime;
:
: Modified: incubator/solr/trunk/src/java/org/apache/solr/search/DocIterator.java
: URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/search/DocIterator.java?rev=409900&r1=409899&r2=409900&view=diff
: ==============================================================================
: --- incubator/solr/trunk/src/java/org/apache/solr/search/DocIterator.java (original)
: +++ incubator/solr/trunk/src/java/org/apache/solr/search/DocIterator.java Sat May 27 17:41:33 2006
: @@ -19,19 +19,35 @@
: import java.util.Iterator;
:
: /**
: + * Simple Iterator of document Ids which may include score information.
: + *
: + * <p>
: + * The order of the documents is determined by the context in which the
: + * DocIterator instance was retrieved.
: + * </p>
: + *
: * @author yonik
: * @version $Id$
: */
: public interface DocIterator extends Iterator<Integer> {
: - public boolean hasNext();
: + // allready declared in superclass, redeclaring prevents javadoc inheritence
: + //public boolean hasNext();
:
: /**
: - * returns the next document id if hasNext()==true
: + * Returns the next document id if hasNext()==true
: + *
: + * <code>
: + * This method is functionally equivilent to <code>next()</code>
: + * @see #next()
: */
: public int nextDoc();
:
: /**
: - * returns the score for the document just returned by nextDoc()
: + * Returns the score for the document just returned by <code>nextDoc()</code>
: + *
: + * <p>
: + * The value returned may be meaningless depending on the context
: + * in which the DocIterator instance was retrieved.
: */
: public float score();
: }
:
: Modified: incubator/solr/trunk/src/java/org/apache/solr/search/DocList.java
: URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/search/DocList.java?rev=409900&r1=409899&r2=409900&view=diff
: ==============================================================================
: --- incubator/solr/trunk/src/java/org/apache/solr/search/DocList.java (original)
: +++ incubator/solr/trunk/src/java/org/apache/solr/search/DocList.java Sat May 27 17:41:33 2006
: @@ -43,7 +43,7 @@
: * (as opposed to just the number collected according
: * to <code>offset()</code> and <code>size()</code>).
: * Hence it's always true that matches() >= size()
: - * @return number of matches for the search(query&filter)
: + * @return number of matches for the search(query & any filters)
: */
: public int matches();
:
: @@ -66,6 +66,18 @@
: */
: public DocList subset(int offset, int len);
:
: + /**
: + * Returns an interator that may be used to iterate over the documents in this DocList
: + *
: + * <p>
: + * The order of the documents returned by this iterator is based on the
: + * Sort order of the search that produced it. The Scoring information
: + * is meaningful only if <code>hasScores()</code> returns true.
: + * </p>
: + * @see #hasScores
: + */
: + public DocIterator iterator();
: +
: /** True if scores were retained */
: public boolean hasScores();
:
:
: Modified: incubator/solr/trunk/src/java/org/apache/solr/search/DocSet.java
: URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/search/DocSet.java?rev=409900&r1=409899&r2=409900&view=diff
: ==============================================================================
: --- incubator/solr/trunk/src/java/org/apache/solr/search/DocSet.java (original)
: +++ incubator/solr/trunk/src/java/org/apache/solr/search/DocSet.java Sat May 27 17:41:33 2006
: @@ -22,33 +22,57 @@
:
: /**
: * <code>DocSet</code> represents an unordered set of Lucene Document Ids.
: + *
: * <p>
: * WARNING: Any DocSet returned from SolrIndexSearcher should <b>not</b> be modified as it may have been retrieved from
: * a cache and could be shared.
: + * </p>
: + *
: * @author yonik
: * @version $Id$
: * @since solr 0.9
: */
: public interface DocSet /* extends Collection<Integer> */ {
: +
: + /**
: + * Adds the specified document if it is not currently in the DocSet
: + * (optional operation).
: + *
: + * @see #addUnique
: + * @throws SolrException if the implimentation does not allow modifications
: + */
: public void add(int doc);
: + /**
: + * Adds a document the caller knows is not currently in the DocSet
: + * (optional operation).
: + *
: + * <p>
: + * This method may be faster then <code>add(doc)</code> in some
: + * implimentaions provided the caller is certain of the precondition.
: + * </p>
: + *
: + * @see #add
: + * @throws SolrException if the implimentation does not allow modifications
: + */
: public void addUnique(int doc);
:
: /**
: - * @return The number of document ids in the set.
: + * Returns the number of documents in the set.
: */
: public int size();
:
: /**
: - *
: - * @param docid
: - * @return
: - * true if the docid is in the set
: + * Returns true if a document is in the DocSet.
: */
: public boolean exists(int docid);
:
: /**
: + * Returns an interator that may be used to iterate over all of the documents in the set.
: *
: - * @return an interator that may be used to iterate over all of the documents in the set.
: + * <p>
: + * The order of the documents returned by this iterator is
: + * non-deterministic, and any scoring information is meaningless
: + * </p>
: */
: public DocIterator iterator();
:
: @@ -75,7 +99,6 @@
: /**
: * Returns the intersection of this set with another set. Neither set is modified - a new DocSet is
: * created and returned.
: - * @param other
: * @return a DocSet representing the intersection
: */
: public DocSet intersection(DocSet other);
: @@ -89,7 +112,6 @@
: /**
: * Returns the union of this set with another set. Neither set is modified - a new DocSet is
: * created and returned.
: - * @param other
: * @return a DocSet representing the union
: */
: public DocSet union(DocSet other);
: @@ -102,7 +124,7 @@
:
: }
:
: -
: +/** A base class that may be usefull for implimenting DocSets */
: abstract class DocSetBase implements DocSet {
:
: // Not implemented efficiently... for testing purposes only
: @@ -126,16 +148,25 @@
: return this.getBits().equals(other.getBits());
: }
:
: + /**
: + * @throws SolrException Base implimentation does not allow modifications
: + */
: public void add(int doc) {
: throw new SolrException(500,"Unsupported Operation");
: }
:
: + /**
: + * @throws SolrException Base implimentation does not allow modifications
: + */
: public void addUnique(int doc) {
: throw new SolrException(500,"Unsupported Operation");
: }
:
: - // Only the inefficient base implementation. DocSets based on
: - // BitSets will return the actual BitSet without making a copy.
: + /**
: + * Inefficient base implementation.
: + *
: + * @see BitDocSet#getBits
: + */
: public BitSet getBits() {
: BitSet bits = new BitSet();
: for (DocIterator iter = iterator(); iter.hasNext();) {
:
: Modified: incubator/solr/trunk/src/java/org/apache/solr/search/DocSlice.java
: URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/search/DocSlice.java?rev=409900&r1=409899&r2=409900&view=diff
: ==============================================================================
: --- incubator/solr/trunk/src/java/org/apache/solr/search/DocSlice.java (original)
: +++ incubator/solr/trunk/src/java/org/apache/solr/search/DocSlice.java Sat May 27 17:41:33 2006
: @@ -33,11 +33,12 @@
: final float maxScore;
:
: /**
: + * Primary constructer for a DocSlice instance.
: *
: * @param offset starting offset for this range of docs
: * @param len length of results
: * @param docs array of docids starting at position 0
: - * @param scores
: + * @param scores array of scores that corrisponds to docs, may be null
: * @param matches total number of matches for the query
: */
: public DocSlice(int offset, int len, int[] docs, float[] scores, int matches, float maxScore) {
:
: Modified: incubator/solr/trunk/src/java/org/apache/solr/util/NamedList.java
: URL: http://svn.apache.org/viewvc/incubator/solr/trunk/src/java/org/apache/solr/util/NamedList.java?rev=409900&r1=409899&r2=409900&view=diff
: ==============================================================================
: --- incubator/solr/trunk/src/java/org/apache/solr/util/NamedList.java (original)
: +++ incubator/solr/trunk/src/java/org/apache/solr/util/NamedList.java Sat May 27 17:41:33 2006
: @@ -20,56 +20,100 @@
: import java.io.Serializable;
:
: /**
: + * A simple container class for modeling an ordered list of name/value pairs.
: + *
: + * <p>
: + * Unlike Maps:
: + * </p>
: + * <ul>
: + * <li>Names may be repeated</li>
: + * <li>Order of elements is maintained</li>
: + * <li>Elements may be accessed by numeric index</li>
: + * <li>Names and Values can both be null</li>
: + * </ul>
: + *
: + * <p>
: + * :TODO: In the future, it would be nice if this extended Map or Collection,
: + * had iterators, used java5 generics, had a faster lookup for
: + * large lists, etc...
: + * It could also have an interface, and multiple implementations.
: + * One might have indexed lookup, one might not.
: + * </p>
: + *
: * @author yonik
: * @version $Id$
: */
: -//
: -// A quick hack of a class to represent a list of name-value pairs.
: -// Unlike a map, order is maintained, and names may
: -// be repeated. Names and values may be null.
: -//
: -// In the future, it would be nice if this extended Map or Collection,
: -// had iterators, used java5 generics, had a faster lookup for
: -// large lists, etc...
: -// It could also have an interface, and multiple implementations.
: -// One might have indexed lookup, one might not.
: -//
: public class NamedList implements Cloneable, Serializable {
: protected final List nvPairs;
:
: + /** Creates an empty instance */
: public NamedList() {
: nvPairs = new ArrayList();
: }
:
: + /**
: + * Creates an instance backed by an explicitly specified list of
: + * pairwise names/values.
: + *
: + * @param nameValuePairs underlying List which should be used to impliment a NamedList; modifying this List will affect the NamedList.
: + */
: public NamedList(List nameValuePairs) {
: nvPairs=nameValuePairs;
: }
:
: + /** The total number of name/value pairs */
: public int size() {
: return nvPairs.size() >> 1;
: }
:
: + /**
: + * The name of the pair at the specified List index
: + *
: + * @return null if no name exists
: + */
: public String getName(int idx) {
: return (String)nvPairs.get(idx << 1);
: }
:
: + /**
: + * The value of the pair at the specified List index
: + *
: + * @return may be null
: + */
: public Object getVal(int idx) {
: return nvPairs.get((idx << 1) + 1);
: }
: -
: +
: + /**
: + * Adds a name/value pair to the end of the list.
: + */
: public void add(String name, Object val) {
: nvPairs.add(name);
: nvPairs.add(val);
: }
:
: + /**
: + * Modifies the name of the pair at the specified index.
: + */
: public void setName(int idx, String name) {
: nvPairs.set(idx<<1, name);
: }
:
: + /**
: + * Modifies the value of the pair at the specified index.
: + */
: public void setVal(int idx, Object val) {
: nvPairs.set((idx<<1)+1, val);
: }
:
: + /**
: + * Scans the list sequentially begining at the specified index and
: + * returns the index of the first pair with the specified name.
: + *
: + * @param name name to look for, may be null
: + * @param start index to begin searching from
: + * @return The index of the first matching pair, -1 if no match
: + */
: public int indexOf(String name, int start) {
: int sz = size();
: for (int i=start; i<sz; i++) {
: @@ -83,15 +127,25 @@
: return -1;
: }
:
: -
: - // gets the value for the first specified name. returns null if not
: - // found or if the value stored was null.
: + /**
: + * Gets the value for the first instance of the specified name
: + * found.
: + *
: + * @return null if not found or if the value stored was null.
: + * @see #indexOf
: + * @see #get(String,int)
: + */
: public Object get(String name) {
: return get(name,0);
: }
:
: - // gets the value for the first specified name starting start.
: - // returns null if not found or if the value stored was null.
: + /**
: + * Gets the value for the first instance of the specified name
: + * found starting at the specified index.
: + *
: + * @return null if not found or if the value stored was null.
: + * @see #indexOf
: + */
: public Object get(String name, int start) {
: int sz = size();
: for (int i=start; i<sz; i++) {
: @@ -120,7 +174,9 @@
: return sb.toString();
: }
:
: -
: + /**
: + * Iterates over the Map and sequentially adds it's key/value pairs
: + */
: public boolean addAll(Map args) {
: Set eset = args.entrySet();
: Iterator iter = eset.iterator();
: @@ -132,7 +188,7 @@
: }
:
: /**
: - * Makes a *shallow copy* of the named list.
: + * Makes a <i>shallow copy</i> of the named list.
: */
: public NamedList clone() {
: ArrayList newList = new ArrayList(nvPairs.size());
:
:
-Hoss