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

http://eyes-free.googlecode.com/ · Java · 234 lines · 87 code · 30 blank · 117 comment · 4 complexity · 2db115659df92e0d222399094b5a0e4e MD5 · raw file

  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. package com.google.android.marvin.talkback;
  17. import android.os.Bundle;
  18. import java.util.LinkedList;
  19. import java.util.List;
  20. /**
  21. * This class represents an utterance composed of text to be spoken and meta
  22. * data about how this text to be spoken. The utterances are cached in a pool of
  23. * instances to be reused as an optimization to reduce new object instantiation.
  24. *
  25. * @author svetoslavganov@google.com (Svetoslav Ganov)
  26. */
  27. public class Utterance {
  28. /**
  29. * Key for obtaining the queuing meta-data property.
  30. */
  31. public static final String KEY_METADATA_QUEUING = "queuing";
  32. /**
  33. * Key for obtaining the earcon rate meta-data property.
  34. */
  35. public static final String KEY_METADATA_EARCON_RATE = "earcon_rate";
  36. /**
  37. * The maximal size of the pool with cached utterances.
  38. */
  39. private static final int MAX_POOL_SIZE = 3;
  40. /**
  41. * Mutex lock for accessing the utterance pool.
  42. */
  43. private static final Object sPoolLock = new Object();
  44. /**
  45. * Pool of cached utterances.
  46. */
  47. private static Utterance sPool;
  48. /**
  49. * The current size of the utterance pool.
  50. */
  51. private static int sPoolSize;
  52. /**
  53. * The text of the utterance.
  54. */
  55. private final StringBuilder mText = new StringBuilder();
  56. /**
  57. * Meta-data of how the utterance should be spoken.
  58. */
  59. private final Bundle mMetadata = new Bundle();
  60. /**
  61. * The list of resource identifiers for this utterance's earcons.
  62. */
  63. private final List<Integer> mEarcons = new LinkedList<Integer>();
  64. /**
  65. * The list of resource identifiers for this utterance's vibration patterns.
  66. */
  67. private final List<Integer> mVibrationPatterns = new LinkedList<Integer>();
  68. /**
  69. * The list of resource identifiers for this utterance's earcons.
  70. */
  71. private final List<Integer> mCustomEarcons = new LinkedList<Integer>();
  72. /**
  73. * The list of resource identifiers for this utterance's vibration patterns.
  74. */
  75. private final List<Integer> mCustomVibrations = new LinkedList<Integer>();
  76. /**
  77. * The next cached utterance
  78. */
  79. private Utterance mNext;
  80. /**
  81. * Denotes if an utterance is currently in the cache pool.
  82. */
  83. private boolean mIsInPool;
  84. /**
  85. * Creates a new instance.
  86. */
  87. private Utterance() {
  88. /* do nothing - reducing constructor visibility */
  89. }
  90. /**
  91. * Returns a cached instance if such is available or a new one is
  92. * instantiated.
  93. *
  94. * @return An instance.
  95. */
  96. public static Utterance obtain() {
  97. return obtain("");
  98. }
  99. /**
  100. * Returns a cached instance if such is available or a new one is
  101. * instantiated and sets its <code>text</code>.
  102. *
  103. * @param text The text of the returned utterance.
  104. * @return An instance.
  105. */
  106. public static Utterance obtain(String text) {
  107. synchronized (sPoolLock) {
  108. if (sPool != null) {
  109. Utterance utterance = sPool;
  110. sPool = sPool.mNext;
  111. sPoolSize--;
  112. utterance.mNext = null;
  113. utterance.mIsInPool = false;
  114. return utterance;
  115. }
  116. return new Utterance();
  117. }
  118. }
  119. /**
  120. * Gets the text of this utterance.
  121. *
  122. * @return The utterance text.
  123. */
  124. public StringBuilder getText() {
  125. return mText;
  126. }
  127. /**
  128. * Gets the list of earcons for this utterance.
  129. *
  130. * @return A list of sound resource identifiers.
  131. */
  132. public List<Integer> getEarcons() {
  133. return mEarcons;
  134. }
  135. /**
  136. * Gets the list of vibration patterns for this utterance.
  137. *
  138. * @return A list of vibration pattern resource identifiers.
  139. */
  140. public List<Integer> getVibrationPatterns() {
  141. return mVibrationPatterns;
  142. }
  143. /**
  144. * @return A list of preference identifiers that correspond to earcon
  145. * resource identifiers.
  146. */
  147. public List<Integer> getCustomEarcons() {
  148. return mCustomEarcons;
  149. }
  150. /**
  151. * @return A list of preference identifiers that correspond to vibration
  152. * pattern resource identifiers.
  153. */
  154. public List<Integer> getCustomVibrations() {
  155. return mCustomVibrations;
  156. }
  157. /**
  158. * Gets the meta-data of this utterance.
  159. *
  160. * @return The utterance meta-data.
  161. */
  162. public Bundle getMetadata() {
  163. return mMetadata;
  164. }
  165. /**
  166. * Return an instance back to be reused.
  167. * <p>
  168. * <b>Note: You must not touch the object after calling this function.</b>
  169. */
  170. public void recycle() {
  171. if (mIsInPool) {
  172. return;
  173. }
  174. clear();
  175. synchronized (sPoolLock) {
  176. if (sPoolSize <= MAX_POOL_SIZE) {
  177. mNext = sPool;
  178. sPool = this;
  179. mIsInPool = true;
  180. sPoolSize++;
  181. }
  182. }
  183. }
  184. /**
  185. * Clears the state of this instance.
  186. */
  187. private void clear() {
  188. mText.delete(0, mText.length());
  189. mMetadata.clear();
  190. mEarcons.clear();
  191. mVibrationPatterns.clear();
  192. mCustomEarcons.clear();
  193. mCustomVibrations.clear();
  194. }
  195. @Override
  196. public String toString() {
  197. StringBuilder builder = new StringBuilder();
  198. builder.append("Text:{");
  199. builder.append(mText);
  200. builder.append("}, Metadata:");
  201. builder.append(mMetadata);
  202. return builder.toString();
  203. }
  204. }