/TalkBack/src/com/google/android/marvin/talkback/Utterance.java

  1/*
  2 * Copyright (C) 2009 The Android Open Source Project
  3 *
  4 * Licensed under the Apache License, Version 2.0 (the "License");
  5 * you may not use this file except in compliance with the License.
  6 * You may obtain a copy of the License at
  7 *
  8 *      http://www.apache.org/licenses/LICENSE-2.0
  9 *
 10 * Unless required by applicable law or agreed to in writing, software
 11 * distributed under the License is distributed on an "AS IS" BASIS,
 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 13 * See the License for the specific language governing permissions and
 14 * limitations under the License.
 15 */
 16
 17package com.google.android.marvin.talkback;
 18
 19import android.os.Bundle;
 20
 21import java.util.LinkedList;
 22import java.util.List;
 23
 24/**
 25 * This class represents an utterance composed of text to be spoken and meta
 26 * data about how this text to be spoken. The utterances are cached in a pool of
 27 * instances to be reused as an optimization to reduce new object instantiation.
 28 * 
 29 * @author svetoslavganov@google.com (Svetoslav Ganov)
 30 */
 31public class Utterance {
 32
 33    /**
 34     * Key for obtaining the queuing meta-data property.
 35     */
 36    public static final String KEY_METADATA_QUEUING = "queuing";
 37
 38    /**
 39     * Key for obtaining the earcon rate meta-data property.
 40     */
 41    public static final String KEY_METADATA_EARCON_RATE = "earcon_rate";
 42
 43    /**
 44     * The maximal size of the pool with cached utterances.
 45     */
 46    private static final int MAX_POOL_SIZE = 3;
 47
 48    /**
 49     * Mutex lock for accessing the utterance pool.
 50     */
 51    private static final Object sPoolLock = new Object();
 52
 53    /**
 54     * Pool of cached utterances.
 55     */
 56    private static Utterance sPool;
 57
 58    /**
 59     * The current size of the utterance pool.
 60     */
 61    private static int sPoolSize;
 62
 63    /**
 64     * The text of the utterance.
 65     */
 66    private final StringBuilder mText = new StringBuilder();
 67
 68    /**
 69     * Meta-data of how the utterance should be spoken.
 70     */
 71    private final Bundle mMetadata = new Bundle();
 72
 73    /**
 74     * The list of resource identifiers for this utterance's earcons.
 75     */
 76    private final List<Integer> mEarcons = new LinkedList<Integer>();
 77
 78    /**
 79     * The list of resource identifiers for this utterance's vibration patterns.
 80     */
 81    private final List<Integer> mVibrationPatterns = new LinkedList<Integer>();
 82
 83    /**
 84     * The list of resource identifiers for this utterance's earcons.
 85     */
 86    private final List<Integer> mCustomEarcons = new LinkedList<Integer>();
 87
 88    /**
 89     * The list of resource identifiers for this utterance's vibration patterns.
 90     */
 91    private final List<Integer> mCustomVibrations = new LinkedList<Integer>();
 92
 93    /**
 94     * The next cached utterance
 95     */
 96    private Utterance mNext;
 97
 98    /**
 99     * Denotes if an utterance is currently in the cache pool.
100     */
101    private boolean mIsInPool;
102
103    /**
104     * Creates a new instance.
105     */
106    private Utterance() {
107        /* do nothing - reducing constructor visibility */
108    }
109
110    /**
111     * Returns a cached instance if such is available or a new one is
112     * instantiated.
113     * 
114     * @return An instance.
115     */
116    public static Utterance obtain() {
117        return obtain("");
118    }
119
120    /**
121     * Returns a cached instance if such is available or a new one is
122     * instantiated and sets its <code>text</code>.
123     * 
124     * @param text The text of the returned utterance.
125     * @return An instance.
126     */
127    public static Utterance obtain(String text) {
128        synchronized (sPoolLock) {
129            if (sPool != null) {
130                Utterance utterance = sPool;
131                sPool = sPool.mNext;
132                sPoolSize--;
133                utterance.mNext = null;
134                utterance.mIsInPool = false;
135                return utterance;
136            }
137            return new Utterance();
138        }
139    }
140
141    /**
142     * Gets the text of this utterance.
143     * 
144     * @return The utterance text.
145     */
146    public StringBuilder getText() {
147        return mText;
148    }
149
150    /**
151     * Gets the list of earcons for this utterance.
152     * 
153     * @return A list of sound resource identifiers.
154     */
155    public List<Integer> getEarcons() {
156        return mEarcons;
157    }
158
159    /**
160     * Gets the list of vibration patterns for this utterance.
161     * 
162     * @return A list of vibration pattern resource identifiers.
163     */
164    public List<Integer> getVibrationPatterns() {
165        return mVibrationPatterns;
166    }
167
168    /**
169     * @return A list of preference identifiers that correspond to earcon
170     *         resource identifiers.
171     */
172    public List<Integer> getCustomEarcons() {
173        return mCustomEarcons;
174    }
175
176    /**
177     * @return A list of preference identifiers that correspond to vibration
178     *         pattern resource identifiers.
179     */
180    public List<Integer> getCustomVibrations() {
181        return mCustomVibrations;
182    }
183
184    /**
185     * Gets the meta-data of this utterance.
186     * 
187     * @return The utterance meta-data.
188     */
189    public Bundle getMetadata() {
190        return mMetadata;
191    }
192
193    /**
194     * Return an instance back to be reused.
195     * <p>
196     * <b>Note: You must not touch the object after calling this function.</b>
197     */
198    public void recycle() {
199        if (mIsInPool) {
200            return;
201        }
202        clear();
203        synchronized (sPoolLock) {
204            if (sPoolSize <= MAX_POOL_SIZE) {
205                mNext = sPool;
206                sPool = this;
207                mIsInPool = true;
208                sPoolSize++;
209            }
210        }
211    }
212
213    /**
214     * Clears the state of this instance.
215     */
216    private void clear() {
217        mText.delete(0, mText.length());
218        mMetadata.clear();
219        mEarcons.clear();
220        mVibrationPatterns.clear();
221        mCustomEarcons.clear();
222        mCustomVibrations.clear();
223    }
224
225    @Override
226    public String toString() {
227        StringBuilder builder = new StringBuilder();
228        builder.append("Text:{");
229        builder.append(mText);
230        builder.append("}, Metadata:");
231        builder.append(mMetadata);
232        return builder.toString();
233    }
234}