Apache
/
lucene
mirror of https://github.com/apache/lucene.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

first significant push at improving javadocs for interfaces/classes used heavily by request handler plugins 

git-svn-id: https://svn.apache.org/repos/asf/incubator/solr/trunk@409900 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Chris M. Hostetter 2006-05-28 00:41:33 +00:00
parent 2fbda0c197
commit e42880a5dc
10 changed files with 284 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
build.xml
View File

@ -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 &amp;copy; ${year} The Apache Software Foundation"

41
src/java/org/apache/solr/core/SolrInfoMBean.java
View File

@ -20,31 +20,50 @@ import java.net.URL;
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();
}

37
src/java/org/apache/solr/request/SolrQueryRequest.java
View File

@ -21,40 +21,59 @@ import org.apache.solr.schema.IndexSchema;
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();
/**

21
src/java/org/apache/solr/request/SolrQueryRequestBase.java
View File

@ -23,9 +23,19 @@ import org.apache.solr.core.SolrCore;
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 @@ public abstract class SolrQueryRequestBase implements SolrQueryRequest {
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();

64
src/java/org/apache/solr/request/SolrQueryResponse.java
View File

@ -22,16 +22,44 @@ import java.util.*;
/**
* <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 @@ public class SolrQueryResponse {
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 @@ public class SolrQueryResponse {
// 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 @@ public class SolrQueryResponse {
* 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 @@ public class SolrQueryResponse {
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 @@ public class SolrQueryResponse {
/**
* 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;

22
src/java/org/apache/solr/search/DocIterator.java
View File

@ -19,19 +19,35 @@ package org.apache.solr.search;
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();
}

14
src/java/org/apache/solr/search/DocList.java
View File

@ -43,7 +43,7 @@ public interface DocList extends DocSet {
* (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 &amp; any filters)
*/
public int matches();
@ -66,6 +66,18 @@ public interface DocList extends DocSet {
*/
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();

53
src/java/org/apache/solr/search/DocSet.java
View File

@ -22,33 +22,57 @@ import java.util.BitSet;
/**
* <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 @@ public interface DocSet /* extends Collection<Integer> */ {
/**
* 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 @@ public interface DocSet /* extends Collection<Integer> */ {
/**
* 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 @@ public interface DocSet /* extends Collection<Integer> */ {
}
/** 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 @@ abstract class DocSetBase implements DocSet {
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();) {

3
src/java/org/apache/solr/search/DocSlice.java
View File

@ -33,11 +33,12 @@ public class DocSlice extends DocSetBase implements DocList {
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) {

94
src/java/org/apache/solr/util/NamedList.java
View File

@ -20,56 +20,100 @@ import java.util.*;
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 @@ public class NamedList implements Cloneable, Serializable {
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 @@ public class NamedList implements Cloneable, Serializable {
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 @@ public class NamedList implements Cloneable, Serializable {
}
/**
* 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());