Index: common-build.xml
===================================================================
--- common-build.xml	(revision 806352)
+++ common-build.xml	(working copy)
@@ -54,7 +54,7 @@
   </path>
 
   <!-- default arguments to pass to JVM executing tests -->
-  <property name="args" value=""/>
+  <property name="args" value="-DTokenStream.onlyUseNewAPI=true"/>
 
   <property name="javac.deprecation" value="off"/>
   <property name="javac.debug" value="on"/>
Index: contrib/highlighter/src/java/org/apache/lucene/search/highlight/QueryScorer.java
===================================================================
--- contrib/highlighter/src/java/org/apache/lucene/search/highlight/QueryScorer.java	(revision 806352)
+++ contrib/highlighter/src/java/org/apache/lucene/search/highlight/QueryScorer.java	(working copy)
@@ -156,8 +156,8 @@
    */
   public TokenStream init(TokenStream tokenStream) throws IOException {
     position = -1;
-    termAtt = (TermAttribute) tokenStream.getAttribute(TermAttribute.class);
-    posIncAtt = (PositionIncrementAttribute) tokenStream.getAttribute(PositionIncrementAttribute.class);
+    termAtt = (TermAttribute) tokenStream.addAttribute(TermAttribute.class);
+    posIncAtt = (PositionIncrementAttribute) tokenStream.addAttribute(PositionIncrementAttribute.class);
     if(!skipInitExtractor) {
       if(fieldWeightedSpanTerms != null) {
         fieldWeightedSpanTerms.clear();
Index: contrib/highlighter/src/java/org/apache/lucene/search/highlight/QueryTermScorer.java
===================================================================
--- contrib/highlighter/src/java/org/apache/lucene/search/highlight/QueryTermScorer.java	(revision 806352)
+++ contrib/highlighter/src/java/org/apache/lucene/search/highlight/QueryTermScorer.java	(working copy)
@@ -95,7 +95,7 @@
    * @see org.apache.lucene.search.highlight.Scorer#init(org.apache.lucene.analysis.TokenStream)
    */
   public TokenStream init(TokenStream tokenStream) {
-    termAtt = (TermAttribute) tokenStream.getAttribute(TermAttribute.class);
+    termAtt = (TermAttribute) tokenStream.addAttribute(TermAttribute.class);
     return null;
   }
 
Index: contrib/highlighter/src/java/org/apache/lucene/search/highlight/SimpleFragmenter.java
===================================================================
--- contrib/highlighter/src/java/org/apache/lucene/search/highlight/SimpleFragmenter.java	(revision 806352)
+++ contrib/highlighter/src/java/org/apache/lucene/search/highlight/SimpleFragmenter.java	(working copy)
@@ -47,7 +47,7 @@
    * @see org.apache.lucene.search.highlight.Fragmenter#start(java.lang.String, org.apache.lucene.analysis.TokenStream)
    */
   public void start(String originalText, TokenStream stream) {
-    offsetAtt = (OffsetAttribute) stream.getAttribute(OffsetAttribute.class);
+    offsetAtt = (OffsetAttribute) stream.addAttribute(OffsetAttribute.class);
     currentNumFrags = 1;
   }
 
Index: contrib/highlighter/src/java/org/apache/lucene/search/highlight/SimpleSpanFragmenter.java
===================================================================
--- contrib/highlighter/src/java/org/apache/lucene/search/highlight/SimpleSpanFragmenter.java	(revision 806352)
+++ contrib/highlighter/src/java/org/apache/lucene/search/highlight/SimpleSpanFragmenter.java	(working copy)
@@ -101,8 +101,8 @@
     position = -1;
     currentNumFrags = 1;
     textSize = originalText.length();
-    termAtt = (TermAttribute) tokenStream.getAttribute(TermAttribute.class);
-    posIncAtt = (PositionIncrementAttribute) tokenStream.getAttribute(PositionIncrementAttribute.class);
-    offsetAtt = (OffsetAttribute) tokenStream.getAttribute(OffsetAttribute.class);
+    termAtt = (TermAttribute) tokenStream.addAttribute(TermAttribute.class);
+    posIncAtt = (PositionIncrementAttribute) tokenStream.addAttribute(PositionIncrementAttribute.class);
+    offsetAtt = (OffsetAttribute) tokenStream.addAttribute(OffsetAttribute.class);
   }
 }
Index: contrib/highlighter/src/java/org/apache/lucene/search/highlight/TokenGroup.java
===================================================================
--- contrib/highlighter/src/java/org/apache/lucene/search/highlight/TokenGroup.java	(revision 806352)
+++ contrib/highlighter/src/java/org/apache/lucene/search/highlight/TokenGroup.java	(working copy)
@@ -41,8 +41,8 @@
   private TermAttribute termAtt;
 
   public TokenGroup(TokenStream tokenStream) {
-    offsetAtt = (OffsetAttribute) tokenStream.getAttribute(OffsetAttribute.class);
-    termAtt = (TermAttribute) tokenStream.getAttribute(TermAttribute.class);
+    offsetAtt = (OffsetAttribute) tokenStream.addAttribute(OffsetAttribute.class);
+    termAtt = (TermAttribute) tokenStream.addAttribute(TermAttribute.class);
   }
 
   void addToken(float score) {
Index: contrib/highlighter/src/test/org/apache/lucene/search/highlight/HighlighterTest.java
===================================================================
--- contrib/highlighter/src/test/org/apache/lucene/search/highlight/HighlighterTest.java	(revision 806352)
+++ contrib/highlighter/src/test/org/apache/lucene/search/highlight/HighlighterTest.java	(working copy)
@@ -1692,9 +1692,9 @@
   public SynonymTokenizer(TokenStream realStream, Map synonyms) {
     this.realStream = realStream;
     this.synonyms = synonyms;
-    realTermAtt = (TermAttribute) realStream.getAttribute(TermAttribute.class);
-    realPosIncrAtt = (PositionIncrementAttribute) realStream.getAttribute(PositionIncrementAttribute.class);
-    realOffsetAtt = (OffsetAttribute) realStream.getAttribute(OffsetAttribute.class);
+    realTermAtt = (TermAttribute) realStream.addAttribute(TermAttribute.class);
+    realPosIncrAtt = (PositionIncrementAttribute) realStream.addAttribute(PositionIncrementAttribute.class);
+    realOffsetAtt = (OffsetAttribute) realStream.addAttribute(OffsetAttribute.class);
 
     termAtt = (TermAttribute) addAttribute(TermAttribute.class);
     posIncrAtt = (PositionIncrementAttribute) addAttribute(PositionIncrementAttribute.class);
Index: src/java/org/apache/lucene/index/TermsHashPerField.java
===================================================================
--- src/java/org/apache/lucene/index/TermsHashPerField.java	(revision 806352)
+++ src/java/org/apache/lucene/index/TermsHashPerField.java	(working copy)
@@ -249,7 +249,7 @@
   private boolean doNextCall;
 
   void start(Fieldable f) {
-    termAtt = (TermAttribute) fieldState.attributeSource.getAttribute(TermAttribute.class);
+    termAtt = (TermAttribute) fieldState.attributeSource.addAttribute(TermAttribute.class);
     consumer.start(f);
     if (nextPerField != null) {
       nextPerField.start(f);
Index: src/java/org/apache/lucene/search/QueryTermVector.java
===================================================================
--- src/java/org/apache/lucene/search/QueryTermVector.java	(revision 806352)
+++ src/java/org/apache/lucene/search/QueryTermVector.java	(working copy)
@@ -61,7 +61,7 @@
           boolean hasMoreTokens = false;
           
           stream.reset(); 
-          TermAttribute termAtt = (TermAttribute) stream.getAttribute(TermAttribute.class);
+          TermAttribute termAtt = (TermAttribute) stream.addAttribute(TermAttribute.class);
 
           hasMoreTokens = stream.incrementToken();
           while (hasMoreTokens) {
Index: src/java/org/apache/lucene/util/AttributeSource.java
===================================================================
--- src/java/org/apache/lucene/util/AttributeSource.java	(revision 806352)
+++ src/java/org/apache/lucene/util/AttributeSource.java	(working copy)
@@ -241,7 +241,11 @@
    * Returns the instance of the passed in Attribute contained in this AttributeSource
    * 
    * @throws IllegalArgumentException if this AttributeSource does not contain the
-   *         Attribute
+   *         Attribute. It is recommended to always use {@link #addAttribute} even in consumers
+   *         of TokenStreams, because you cannot know if a specific TokenStream really uses
+   *         a specific Attribute. {@link #addAttribute} will automatically make the attribute
+   *         available. If you want to only use the attribute, if it is available (to optimize
+   *         consuming), use {@link #hasAttribute}.
    */
   public AttributeImpl getAttribute(Class attClass) {
     AttributeImpl att = (AttributeImpl) this.attributes.get(attClass);
Index: src/test/org/apache/lucene/analysis/TestTeeTokenFilter.java
===================================================================
--- src/test/org/apache/lucene/analysis/TestTeeTokenFilter.java	(revision 806352)
+++ src/test/org/apache/lucene/analysis/TestTeeTokenFilter.java	(working copy)
@@ -42,6 +42,9 @@
 
   protected void setUp() throws Exception {
     super.setUp();
+    // force this to false for this TokenStream
+    TokenStream.setOnlyUseNewAPI(false);
+
     tokens1 = new String[]{"The", "quick", "Burgundy", "Fox", "jumped", "over", "the", "lazy", "Red", "Dogs"};
     tokens2 = new String[]{"The", "Lazy", "Dogs", "should", "stay", "on", "the", "porch"};
     buffer1 = new StringBuffer();
Index: src/test/org/apache/lucene/analysis/TestTokenStreamBWComp.java
===================================================================
--- src/test/org/apache/lucene/analysis/TestTokenStreamBWComp.java	(revision 806352)
+++ src/test/org/apache/lucene/analysis/TestTokenStreamBWComp.java	(working copy)
@@ -93,6 +93,12 @@
     }
     
   }
+  
+  protected void setUp() throws Exception {
+    super.setUp();
+    // force this to false for the BW Tests
+    TokenStream.setOnlyUseNewAPI(false);
+  }
 
   // test the chain: The one and only term "TokenStream" should be declared as proper noun:
 
Index: src/test/org/apache/lucene/util/LuceneTestCase.java
===================================================================
--- src/test/org/apache/lucene/util/LuceneTestCase.java	(revision 806352)
+++ src/test/org/apache/lucene/util/LuceneTestCase.java	(working copy)
@@ -24,6 +24,7 @@
 
 import junit.framework.TestCase;
 
+import org.apache.lucene.analysis.TokenStream;
 import org.apache.lucene.index.ConcurrentMergeScheduler;
 import org.apache.lucene.search.FieldCache;
 import org.apache.lucene.search.FieldCache.CacheEntry;
@@ -59,6 +60,9 @@
 
   protected void setUp() throws Exception {
     ConcurrentMergeScheduler.setTestMode();
+    TokenStream.setOnlyUseNewAPI(
+      Boolean.parseBoolean(System.getProperty("TokenStream.onlyUseNewAPI", Boolean.FALSE.toString()))
+    );
   }
 
   /**