SOLR-489: Add in deprecation comments

git-svn-id: https://svn.apache.org/repos/asf/lucene/solr/trunk@684908 13f79535-47bb-0310-9956-ffa450edef68

CHANGES.txt

@@ -588,6 +588,8 @@ Other Changes
 
 21. SOLR-682: Scripts now support FreeBSD (Richard Trey Hyde via gsingers)
 
+22. SOLR-489: Added in deprecation comments.  (Sean Timm, Lars Kothoff via gsingers)
+
 Build
  1. SOLR-411.  Changed the names of the Solr JARs to use the defacto standard JAR names based on
     project-name-version.jar.  This yields, for example:

src/java/org/apache/solr/analysis/WordDelimiterFilter.java

@@ -176,12 +176,24 @@ final class WordDelimiterFilter extends TokenFilter {
   public WordDelimiterFilter(TokenStream in, int generateWordParts, int generateNumberParts, int catenateWords, int catenateNumbers, int catenateAll, int splitOnCaseChange, int preserveOriginal) {
     this(in, defaultWordDelimTable, generateWordParts, generateNumberParts, catenateWords, catenateNumbers, catenateAll, splitOnCaseChange, preserveOriginal);
   }
-  /** Compatibility constructor */
+  /**
+   * Compatibility constructor
+   * 
+   * @deprecated Use
+   *             {@link #WordDelimiterFilter(TokenStream, int, int, int, int, int, int, int)}
+   *             instead.
+   */
   @Deprecated
   public WordDelimiterFilter(TokenStream in, byte[] charTypeTable, int generateWordParts, int generateNumberParts, int catenateWords, int catenateNumbers, int catenateAll) {
     this(in, charTypeTable, generateWordParts, generateNumberParts, catenateWords, catenateNumbers, catenateAll, 1, 0);
   }
-  /** Compatibility constructor */
+  /**
+   * Compatibility constructor
+   * 
+   * @deprecated Use
+   *             {@link #WordDelimiterFilter(TokenStream, int, int, int, int, int, int, int)}
+   *             instead.
+   */
   @Deprecated
   public WordDelimiterFilter(TokenStream in, int generateWordParts, int generateNumberParts, int catenateWords, int catenateNumbers, int catenateAll) {
     this(in, defaultWordDelimTable, generateWordParts, generateNumberParts, catenateWords, catenateNumbers, catenateAll, 1, 0);

src/java/org/apache/solr/core/Config.java

@@ -45,6 +45,9 @@ public class Config {
   private final String name;
   private final SolrResourceLoader loader;
 
+  /**
+   * @deprecated Use {@link #Config(SolrResourceLoader, String, InputStream, String)} instead. 
+   */
   @Deprecated
   public Config(String name, InputStream is, String prefix) throws ParserConfigurationException, IOException, SAXException 
   {
@@ -254,31 +257,49 @@ public class Config {
   // The following functions were moved to ResourceLoader
   //-----------------------------------------------------------------------------
   
+   /**
+    * @deprecated Use {@link SolrResourceLoader#getConfigDir()} instead.
+    */
   @Deprecated
   public String getConfigDir() {
     return loader.getConfigDir();
   }
 
+  /**
+   * @deprecated Use {@link SolrResourceLoader#openResource(String)} instead.
+   */
   @Deprecated
   public InputStream openResource(String resource) {
     return loader.openResource(resource);
   }
 
+  /**
+   * @deprecated Use {@link SolrResourceLoader#getLines(String)} instead.
+   */
   @Deprecated
   public List<String> getLines(String resource) throws IOException {
     return loader.getLines(resource);
   }
 
+  /**
+   * @deprecated Use {@link SolrResourceLoader#findClass(String, String[])} instead.
+   */
   @Deprecated
   public Class findClass(String cname, String... subpackages) {
     return loader.findClass(cname, subpackages);
   }
 
+  /**
+   * @deprecated Use {@link SolrResourceLoader#newInstance(String, String[])} instead.
+   */
   @Deprecated
   public Object newInstance(String cname, String ... subpackages) {
     return loader.newInstance(cname, subpackages);
   }
   
+  /**
+   * @deprecated Use {@link SolrResourceLoader#getInstanceDir()} instead.
+   */
   @Deprecated
   public String getInstanceDir() {
     return loader.getInstanceDir();

src/java/org/apache/solr/core/SolrConfig.java

@@ -52,7 +52,10 @@ public class SolrConfig extends Config {
 
   public static final String DEFAULT_CONF_FILE = "solrconfig.xml";
 
-  // Compatibility feature for single-core (pre-solr{215,350} patch); should go away at solr-2.0
+  /**
+   * Compatibility feature for single-core (pre-solr{215,350} patch); should go away at solr-2.0
+   * @deprecated Use {@link SolrCore#getSolrConfig()} instead.
+   */
   @Deprecated
   public static SolrConfig config = null; 
 
@@ -180,7 +183,10 @@ public class SolrConfig extends Config {
     return httpCachingConfig;
   }
   
-  // ping query request parameters
+  /**
+   * ping query request parameters
+   * @deprecated Use {@link PingRequestHandler} instead.
+   */
   @Deprecated
   private final NamedList pingQueryParams;
 

src/java/org/apache/solr/core/SolrCore.java

@@ -90,6 +90,9 @@ public final class SolrCore {
   
   public long getStartTime() { return startTime; }
 
+  /**
+   * @deprecated Use {@link MultiCore#getCore(String)} instead.
+   */
   @Deprecated
   private static SolrCore instance;
 
@@ -125,7 +128,7 @@ public final class SolrCore {
   
   /**
    * Gets the configuration resource name used by this core instance.
-   * @see #getConfigResource()
+   * @deprecated Use {@link #getConfigResource()} instead.
    */
   @Deprecated
   public String getConfigFile() {
@@ -148,7 +151,7 @@ public final class SolrCore {
 
   /**
    * Gets the schema resource name used by this core instance.
-   * @see #getSchemaResource() 
+   * @deprecated Use {@link #getSchemaResource()} instead.
    */
   @Deprecated
   public String getSchemaFile() {
@@ -341,6 +344,8 @@ public final class SolrCore {
   /** 
    * @return the last core initialized.  If you are using multiple cores, 
    * this is not a function to use.
+   * 
+   * @deprecated Use {@link MultiCore#getCore(String)} instead.
    */
   @Deprecated
   public static SolrCore getSolrCore() {
@@ -1162,6 +1167,9 @@ public final class SolrCore {
        (int)(rsp.getEndTime() - req.getStartTime()));*/
   }
 
+  /**
+   * @deprecated Use {@link #execute(SolrRequestHandler, SolrQueryRequest, SolrQueryResponse)} instead. 
+   */
   @Deprecated
   public void execute(SolrQueryRequest req, SolrQueryResponse rsp) {
     SolrRequestHandler handler = getRequestHandler(req.getQueryType());

src/java/org/apache/solr/handler/XmlUpdateRequestHandler.java

@@ -374,6 +374,10 @@ public class XmlUpdateRequestHandler extends RequestHandlerBase
    * success or failure from an XML formated Update (from the Reader)
    * 
    * @since solr 1.2
+   * 
+   * @deprecated Use
+   *             {@link #processUpdate(UpdateRequestProcessor, XMLStreamReader)}
+   *             instead.
    */
   @Deprecated
   public void doLegacyUpdate(Reader input, Writer output) {

src/java/org/apache/solr/handler/admin/ShowFileRequestHandler.java

@@ -193,6 +193,9 @@ public class ShowFileRequestHandler extends RequestHandlerBase
    * 
    * It is only used so that we can get rid of "/admin/get-file.jsp" and include
    * "admin-extra.html" in "/admin/index.html" using jsp scriptlets
+   * 
+   * @deprecated This functionality is implemented in
+   *             {@link #handleRequestBody(SolrQueryRequest, SolrQueryResponse)}.
    */
   @Deprecated
   public static String getFileContents( String path )

src/java/org/apache/solr/request/SolrQueryRequest.java

@@ -19,6 +19,7 @@ package org.apache.solr.request;
 
 import org.apache.solr.search.SolrIndexSearcher;
 import org.apache.solr.schema.IndexSchema;
+import org.apache.solr.common.params.CommonParams;
 import org.apache.solr.common.params.SolrParams;
 import org.apache.solr.common.util.ContentStream;
 import org.apache.solr.core.SolrCore;
@@ -66,6 +67,7 @@ public interface SolrQueryRequest {
    * 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.
+   * @deprecated Use {@link #getParams()} instead.
    */
   @Deprecated
   public String getParam(String name);
@@ -73,12 +75,14 @@ public interface SolrQueryRequest {
   /**
    * Returns the input parameter values for the specified name
    * @return the values; may be null or empty depending on implementation
+   * @deprecated Use {@link #getParams()} instead.
    */
   @Deprecated
   public String[] getParams(String name);
 
   /**
    * Returns the primary query string parameter of the request
+   * @deprecated Use {@link #getParams()} and {@link CommonParams#Q} instead.
    */
   @Deprecated
   public String getQueryString();
@@ -86,15 +90,20 @@ public interface SolrQueryRequest {
   /**
    * Signifies the syntax and the handler that should be used
    * to execute this query.
+   * @deprecated Use {@link #getParams()} and {@link CommonParams#QT} instead.
    */
   @Deprecated
   public String getQueryType();
 
-  /** starting position in matches to return to client */
+  /** starting position in matches to return to client
+   * @deprecated Use {@link #getParams()} and {@link CommonParams#START} instead.
+   */
   @Deprecated
   public int getStart();
 
-  /** number of matching documents to return */
+  /** number of matching documents to return
+   * @deprecated Use {@link #getParams()} and {@link CommonParams#ROWS} instead.
+   */
   @Deprecated
   public int getLimit();
 

src/java/org/apache/solr/request/SolrQueryRequestBase.java

@@ -98,16 +98,24 @@ public abstract class SolrQueryRequestBase implements SolrQueryRequest {
     this.params = params;
   }
 
+  /**
+   * @deprecated Use {@link #getParams()} instead.
+   */
+  @Deprecated
   public String getParam(String name) {
     return params.get(name);
   }
 
+  /**
+   * @deprecated Use {@link #getParams()} instead.
+   */
+  @Deprecated
   public String[] getParams(String name) {
     return params.getParams(name);
   }
 
   /**
-   * use getParams().required().getInt( name ) instead
+   * @deprecated use getParams().required().getInt( name ) instead
    */
   @Deprecated
   public int getIntParam(String name) {
@@ -119,7 +127,7 @@ public abstract class SolrQueryRequestBase implements SolrQueryRequest {
   }
 
   /**
-   * use getParams().required().getInt( name ) instead
+   * @deprecated use getParams().required().getInt( name ) instead
    */
   @Deprecated
   public int getIntParam(String name, int defval) {
@@ -128,7 +136,7 @@ public abstract class SolrQueryRequestBase implements SolrQueryRequest {
   }
 
   /**
-   * use getParams().required().getParam( name ) instead
+   * @deprecated use getParams().required().getParam( name ) instead
    */
   @Deprecated
   public String getStrParam(String name) {
@@ -140,7 +148,7 @@ public abstract class SolrQueryRequestBase implements SolrQueryRequest {
   }
 
   /**
-   * use getParams().required().getParam( name ) instead
+   * @deprecated use getParams().required().getParam( name ) instead
    */
   @Deprecated
   public String getStrParam(String name, String defval) {
@@ -148,23 +156,35 @@ public abstract class SolrQueryRequestBase implements SolrQueryRequest {
     return s==null ? defval : s;
   }
 
+  /**
+   * @deprecated Use {@link #getParams()} and {@link CommonParams#Q} instead.
+   */
   @Deprecated
   public String getQueryString() {
     return params.get(CommonParams.Q);
   }
 
+  /**
+   * @deprecated Use {@link #getParams()} and {@link CommonParams#QT} instead.
+   */
   @Deprecated
   public String getQueryType() {
     return params.get(CommonParams.QT);
   }
 
-  // starting position in matches to return to client
+  /**
+   * starting position in matches to return to client
+   * @deprecated Use {@link #getParams()} and {@link CommonParams#START} instead.
+   */
   @Deprecated
   public int getStart() {
     return params.getInt(CommonParams.START, 0);
   }
 
-  // number of matching documents to return
+  /**
+   * number of matching documents to return
+   * @deprecated Use {@link #getParams()} and {@link CommonParams#ROWS} instead.
+   */
   @Deprecated
   public int getLimit() {
     return params.getInt(CommonParams.ROWS, 10);

src/java/org/apache/solr/schema/IndexSchema.java

@@ -67,6 +67,7 @@ public final class IndexSchema {
    * Config path directory searching rules.
    *
    * @see Config#openResource
+   * @deprecated Use {@link #IndexSchema(SolrConfig, String, InputStream)} instead.
    */
   @Deprecated
   public IndexSchema(SolrConfig solrConfig, String name) {
@@ -121,6 +122,8 @@ public final class IndexSchema {
   /**
    * Direct access to the InputStream for the schemaFile used by this instance.
    * @see Config#openResource
+   * @deprecated Use {@link #getSolrConfig()} and open a resource input stream
+   *             for {@link #getResourceName()} instead.
    */
   @Deprecated
   public InputStream getInputStream() {
@@ -128,7 +131,7 @@ public final class IndexSchema {
   }
 
   /** Gets the name of the schema file.
-   * @see IndexSchema#getResourceName
+   * @deprecated Use {@link #getResourceName()} instead.
    */
   @Deprecated
   public String getSchemaFile() {
@@ -136,7 +139,7 @@ public final class IndexSchema {
   }
 
   /** The Name of this schema (as specified in the schema file)
-   * @see IndexSchema#getSchemaName
+   * @deprecated Use {@link #getSchemaName()} instead.
    */
   @Deprecated
   public String getName() { return name; }
@@ -249,6 +252,7 @@ public final class IndexSchema {
    * Name of the default search field specified in the schema file
    * @deprecated use getSolrQueryParser().getField()
    */
+  @Deprecated
   public String getDefaultSearchFieldName() {
     return defaultSearchFieldName;
   }
@@ -257,6 +261,7 @@ public final class IndexSchema {
    * default operator ("AND" or "OR") for QueryParser
    * @deprecated use getSolrQueryParser().getDefaultOperator()
    */
+  @Deprecated
   public String getQueryParserDefaultOperator() {
     return queryParserDefaultOperator;
   }

src/java/org/apache/solr/search/DocSet.java

@@ -83,6 +83,8 @@ public interface DocSet /* extends Collection<Integer> */ {
    *
    * @return
    * An OpenBitSet with the bit number of every docid set in the set.
+   * 
+   * @deprecated Use {@link #iterator()} to access all docs instead.
    */
   @Deprecated
   public OpenBitSet getBits();

src/java/org/apache/solr/tst/OldRequestHandler.java

@@ -36,6 +36,8 @@ import org.apache.solr.request.SolrQueryRequest;
 
 /**
  * @version $Id$
+ * 
+ * @deprecated Test against the real request handlers instead.
  */
 @Deprecated
 public class OldRequestHandler implements SolrRequestHandler {

src/java/org/apache/solr/tst/TestRequestHandler.java

@@ -40,6 +40,8 @@ import org.apache.solr.request.SolrQueryResponse;
 
 /**
  * @version $Id$
+ * 
+ * @deprecated Test against the real request handlers instead.
  */
 @Deprecated
 public class TestRequestHandler implements SolrRequestHandler {

src/java/org/apache/solr/util/CommonParams.java

@@ -24,6 +24,7 @@ import java.util.logging.Logger;
 /**
  * A collection on common params, both for Plugin initialization and
  * for Requests.
+ * @deprecated Use {@link org.apache.solr.common.params.CommonParams} instead.
  */
 @Deprecated
 public class CommonParams implements org.apache.solr.common.params.CommonParams {

src/java/org/apache/solr/util/DisMaxParams.java

@@ -23,6 +23,7 @@ import org.apache.solr.common.util.NamedList;
 
 /**
  * This class is scheduled for deletion.  Please update your code to the moved package.
+ * @deprecated Use {@link org.apache.solr.common.params.DisMaxParams} instead.
  */
 @Deprecated
 public class DisMaxParams extends CommonParams implements org.apache.solr.common.params.DisMaxParams {

src/webapp/src/org/apache/solr/servlet/SolrServlet.java

@@ -35,6 +35,10 @@ import org.apache.solr.request.SolrQueryResponse;
 import org.apache.solr.request.SolrRequestHandler;
 
 /**
+ * @deprecated Register a standard request handler instead of using this
+ *             servlet. Add <requestHandler name="standard"
+ *             class="solr.StandardRequestHandler" default="true"> to
+ *             solrconfig.xml.
  */
 
 @Deprecated