Class VoiceGrammar.Builder¶

java.lang.Object
- com.iristick.smartglass.core.VoiceGrammar.Builder

Enclosing interface:: VoiceGrammar

public abstract static class VoiceGrammar.Builder
extends Object

This class allows to construct immutable voice command grammar objects.

To obtain a builder instance, use the create() method.

Builder instances are single-use only. Any attempt to further modify the builder after build() has built a grammar object will result in an IllegalStateException.

Constructor Summary¶

Constructor and Description
`Builder()`

Method Summary¶

Modifier and Type	Method and Description
`abstract VoiceGrammar.Builder`	`addToken(int token)` Add a token to the group at the top of the grammar stack.
`abstract VoiceGrammar.Builder`	`addToken(int token, int tag)` Add a token to the group at the top of the grammar stack and associate it with the given tag.
`abstract VoiceGrammar.Builder`	`addToken(String token)` Add a token to the group at the top of the grammar stack.
`abstract VoiceGrammar.Builder`	`addToken(String token, int tag)` Add a token to the group at the top of the grammar stack and associate it with the given tag.
`abstract VoiceGrammar.Builder`	`addTokens(int tokens)` Utility method to add all tokens from a string array resource.
`VoiceGrammar.Builder`	`addTokens(int tokens, int firstTag)` Utility method to add all tokens from a string array resource and associate each token with a tag.
`abstract VoiceGrammar.Builder`	`addTokens(int tokens, int firstTag, int tagIncrement)` Utility method to add all tokens from a string array resource and associate each token with a tag.
`abstract VoiceGrammar.Builder`	`addTokens(List<String> tokens)` Utility method to add all tokens from a list.
`VoiceGrammar.Builder`	`addTokens(List<String> tokens, int firstTag)` Utility method to add all tokens from a list and associate each token with a tag.
`abstract VoiceGrammar.Builder`	`addTokens(List<String> tokens, int firstTag, int tagIncrement)` Utility method to add all tokens from a list and associate each token with a tag.
`abstract VoiceGrammar`	`build()` Builds the grammar according to the recorded instructions.
`static VoiceGrammar.Builder`	`create()` Creates a new empty builder instance.
`static VoiceGrammar.Builder`	`create(Context context)` Creates a new empty builder instance.
`abstract VoiceGrammar.Builder`	`popGroup()` Pops the top-most group from the grammar stack.
`abstract VoiceGrammar.Builder`	`popToRootGroup()` Repeatedly call `popGroup()` until only the root sequential group remains at the top of the stack.
`abstract VoiceGrammar.Builder`	`pushAlternativeGroup()` Pushes a new alternative group onto the grammar stack.
`abstract VoiceGrammar.Builder`	`pushAlternativeGroup(int repeatMin, int repeatMax)` Pushes a new alternative group onto the grammar stack.
`abstract VoiceGrammar.Builder`	`pushSequentialGroup()` Pushes a new sequential group onto the grammar stack.
`abstract VoiceGrammar.Builder`	`pushSequentialGroup(int repeatMin, int repeatMax)` Pushes a new sequential group onto the grammar stack.
`abstract VoiceGrammar.Builder`	`setCallback(VoiceEvent.Callback callback, Handler handler)` Set the callback to be invoked for this grammar.

Methods inherited from class java.lang.Object ¶

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail¶

Builder¶

public Builder()

Method Detail¶

create¶

@NonNull
 @CheckResult
public static VoiceGrammar.Builder create()

Creates a new empty builder instance.

Returns:: A new builder instance for building VoiceGrammar objects.

create¶

@NonNull
 @CheckResult
public static VoiceGrammar.Builder create(@Nullable
                                                                 Context context)

Creates a new empty builder instance.

Parameters:: context - Context object. If not null, this builder supports the convenience methods with resource identifiers.
Returns:: A new builder instance for building VoiceGrammar objects.

addToken¶

@NonNull
public abstract VoiceGrammar.Builder addToken(@NonNull
                                                       String token)

Add a token to the group at the top of the grammar stack.

Tokens are assumed to be in the currently configured locale, or in English if that locale is not supported. Special characters, such as punctuation, are ignored. A token may consist of multiple words, separated by spaces.

Parameters:: token - String containing a single token.
Returns:: This builder instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.
See Also:: addToken(String, int)

addToken¶

@NonNull
public abstract VoiceGrammar.Builder addToken(@StringRes
                                                       int token)

Add a token to the group at the top of the grammar stack.

Tokens are assumed to be in the currently configured locale, or in English if that locale is not supported. Special characters, such as punctuation, are ignored. A token may consist of multiple words, separated by spaces.

Parameters:: token - String resource containing a single token.
Returns:: This builder instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.; UnsupportedOperationException - if the builder was initialized without valid context.
See Also:: addToken(String, int), create(Context)

addToken¶

@NonNull
public abstract VoiceGrammar.Builder addToken(@NonNull
                                                       String token,
                                                       int tag)

Add a token to the group at the top of the grammar stack and associate it with the given tag.

Tokens are assumed to be in the currently configured locale, or in English if that locale is not supported. Special characters, such as punctuation, are ignored. A token may consist of multiple words, separated by spaces.

Parameters:: token - String containing a single token.; tag - Numeric tag for this token. When the recognition engine has recognized this token, this tag is part of the VoiceEvent.getTags() list of tags} of the voice event.
Returns:: This builder instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.
See Also:: addToken(String)

addToken¶

@NonNull
public abstract VoiceGrammar.Builder addToken(@StringRes
                                                       int token,
                                                       int tag)

Add a token to the group at the top of the grammar stack and associate it with the given tag.

Tokens are assumed to be in the currently configured locale, or in English if that locale is not supported. Special characters, such as punctuation, are ignored. A token may consist of multiple words, separated by spaces.

Parameters:: token - String resource containing a single token.; tag - Numeric tag for this token. When the recognition engine has recognized this token, this tag is part of the VoiceEvent.getTags() list of tags} of the voice event.
Returns:: This builder instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.; UnsupportedOperationException - if the builder was initialized without valid context.
See Also:: addToken(String, int), create(Context)

addTokens¶

@NonNull
public abstract VoiceGrammar.Builder addTokens(@NonNull
                                                        List<String> tokens)

Utility method to add all tokens from a list.

This method is equivalent to

 
 for (String token : tokens) {
     builder.addToken(token);
 }

Tokens are assumed to be in the currently configured locale, or in English if that locale is not supported. Special characters, such as punctuation, are ignored. A token may consist of multiple words, separated by spaces.

Parameters:: tokens - List of tokens.
Returns:: This builder instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.; NullPointerException - if the list contains null.
See Also:: addToken(String)

addTokens¶

@NonNull
public VoiceGrammar.Builder addTokens(@NonNull
                                               List<String> tokens,
                                               int firstTag)

Utility method to add all tokens from a list and associate each token with a tag.

This method is equivalent to

 
 int tag = firstTag;
 for (String token : tokens) {
     builder.addToken(token, tag);
     ++tag;
 }

Tokens are assumed to be in the currently configured locale, or in English if that locale is not supported. Special characters, such as punctuation, are ignored. A token may consist of multiple words, separated by spaces.

Parameters:: tokens - List of tokens; firstTag - Numeric tag of the first token.
Returns:: This builder instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.; NullPointerException - if the list contains null.
See Also:: addToken(String, int)

addTokens¶

@NonNull
public abstract VoiceGrammar.Builder addTokens(@NonNull
                                                        List<String> tokens,
                                                        int firstTag,
                                                        int tagIncrement)

Utility method to add all tokens from a list and associate each token with a tag.

This method is equivalent to

 
 int tag = firstTag;
 for (String token : tokens) {
     builder.addToken(token, tag);
     tag += tagIncrement;
 }

Tokens are assumed to be in the currently configured locale, or in English if that locale is not supported. Special characters, such as punctuation, are ignored. A token may consist of multiple words, separated by spaces.

Parameters:: tokens - List of tokens; firstTag - Numeric tag of the first token.; tagIncrement - Increment of the tag associated with each token.
Returns:: This builder instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.; NullPointerException - if the list contains null.
See Also:: addToken(String, int)

addTokens¶

@NonNull
public abstract VoiceGrammar.Builder addTokens(@ArrayRes
                                                        int tokens)

Utility method to add all tokens from a string array resource.

This method is equivalent to

 
 String[] resolvedTokens = context.getResources().getStringArray(tokens);
 for (String token : resolvedTokens) {
     builder.addToken(token);
 }

Tokens are assumed to be in the currently configured locale, or in English if that locale is not supported. Special characters, such as punctuation, are ignored. A token may consist of multiple words, separated by spaces.

Parameters:: tokens - String array resource containing a list of tokens.
Returns:: This builder instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.; UnsupportedOperationException - if the builder was initialized without valid context.
See Also:: addToken(String), create(Context)

addTokens¶

@NonNull
public VoiceGrammar.Builder addTokens(@ArrayRes
                                               int tokens,
                                               int firstTag)

Utility method to add all tokens from a string array resource and associate each token with a tag.

This method is equivalent to

 
 String[] resolvedTokens = context.getResources().getStringArray(tokens);
 int tag = firstTag;
 for (String token : resolvedTokens) {
     builder.addToken(token, tag);
     ++tag;
 }

Tokens are assumed to be in the currently configured locale, or in English if that locale is not supported. Special characters, such as punctuation, are ignored. A token may consist of multiple words, separated by spaces.

Parameters:: tokens - String array resource containing a list of tokens.; firstTag - Numeric tag of the first token.
Returns:: This builder instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.; UnsupportedOperationException - if the builder was initialized without valid context.
See Also:: addToken(String, int), create(Context)

addTokens¶

@NonNull
public abstract VoiceGrammar.Builder addTokens(@ArrayRes
                                                        int tokens,
                                                        int firstTag,
                                                        int tagIncrement)

Utility method to add all tokens from a string array resource and associate each token with a tag.

This method is equivalent to

 
 String[] resolvedTokens = context.getResources().getStringArray(tokens);
 int tag = firstTag;
 for (String token : resolvedTokens) {
     builder.addToken(token, tag);
     tag += tagIncrement;
 }

Tokens are assumed to be in the currently configured locale, or in English if that locale is not supported. Special characters, such as punctuation, are ignored. A token may consist of multiple words, separated by spaces.

Parameters:: tokens - String array resource containing a list of tokens.; firstTag - Numeric tag of the first token.; tagIncrement - Increment of the tag associated with each token.
Returns:: This builder instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.; UnsupportedOperationException - if the builder was initialized without valid context.
See Also:: addToken(String, int), create(Context)

pushSequentialGroup¶

@NonNull
public abstract VoiceGrammar.Builder pushSequentialGroup()

Pushes a new sequential group onto the grammar stack. Patterns in a sequential group must be uttered one after the other in order of appearance. This is equivalent to:

 
     builder.pushSequentialGroup(1, 1);

Returns:: This instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.
See Also:: pushSequentialGroup(int, int), popGroup()

pushSequentialGroup¶

@NonNull
public abstract VoiceGrammar.Builder pushSequentialGroup(int repeatMin,
                                                                  int repeatMax)

Pushes a new sequential group onto the grammar stack. The entire group must be uttered between repeatMin and repeatMax (inclusive) times. Patterns in a sequential group must be uttered one after the other in order of appearance.

Parameters:: repeatMin - Minimum number of repetitions of the group. This must be a positive value.; repeatMax - Maximum number of repetitions of the group. This value must be at least repeatMin for a bounded maximum number of repetitions or VoiceGrammar.REPEAT_UNBOUNDED.
Returns:: This instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.
See Also:: pushSequentialGroup(int, int), popGroup()

pushAlternativeGroup¶

@NonNull
public abstract VoiceGrammar.Builder pushAlternativeGroup()

Pushes a new alternative group onto the grammar stack.

Patterns in an alternative group provide options. Exactly one of the members of the group must be uttered. This is equivalent to:

 
     builder.pushAlternativeGroup(1, 1);

Returns:: This instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.
See Also:: pushAlternativeGroup(int, int), popGroup()

pushAlternativeGroup¶

@NonNull
public abstract VoiceGrammar.Builder pushAlternativeGroup(int repeatMin,
                                                                   int repeatMax)

Pushes a new alternative group onto the grammar stack. The entire group must be uttered between repeatMin and repeatMax (inclusive) times.

Patterns in an alternative group provide options. Exactly one of the members of the group must be uttered.

Parameters:: repeatMin - Minimum number of repetitions of the group. This must be a positive value.; repeatMax - Maximum number of repetitions of the group. This value must be at least repeatMin for a bounded maximum number of repetitions or VoiceGrammar.REPEAT_UNBOUNDED.
Returns:: This instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.
See Also:: pushAlternativeGroup(int, int), popGroup()

popGroup¶

@NonNull
public abstract VoiceGrammar.Builder popGroup()

Pops the top-most group from the grammar stack.

This operation fails if the root sequential group is at the top of the stack.

Returns:: This instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.
See Also:: pushSequentialGroup(), pushAlternativeGroup()

popToRootGroup¶

@NonNull
public abstract VoiceGrammar.Builder popToRootGroup()

Repeatedly call popGroup() until only the root sequential group remains at the top of the stack.

Returns:: This instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.
See Also:: pushSequentialGroup(), pushAlternativeGroup()

setCallback¶

@NonNull
public abstract VoiceGrammar.Builder setCallback(@NonNull
                                                          VoiceEvent.Callback callback,
                                                          @Nullable
                                                          Handler handler)

Set the callback to be invoked for this grammar.

Parameters:: callback - The callback to invoke when a matching voice command is recognized.; handler - Handler on which the callback is invoked. If null, the main looper callback is used.
Returns:: This instance for method chaining.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.

build¶

@NonNull
 @CheckResult
public abstract VoiceGrammar build()

Builds the grammar according to the recorded instructions.

Builders are single-use only.

Returns:: A finished grammar object.
Throws:: IllegalStateException - if a VoiceGrammar was already built from this builder.; IllegalStateException - if the grammar is empty.; IllegalStateException - if no callback was set.
See Also:: Headset.startVoice(VoiceGrammar)

Class VoiceGrammar.Builder¶

Constructor Summary¶

Method Summary¶

Methods inherited from class java.lang.Object¶

Constructor Detail¶

Builder¶

Method Detail¶

create¶

create¶

addToken¶

addToken¶

addToken¶

addToken¶

addTokens¶

addTokens¶

addTokens¶

addTokens¶

addTokens¶

addTokens¶

pushSequentialGroup¶

pushSequentialGroup¶

pushAlternativeGroup¶

pushAlternativeGroup¶

popGroup¶

popToRootGroup¶

setCallback¶

build¶

Methods inherited from class java.lang.Object ¶