io.klerch.alexa.state.handler

Interface AlexaStateHandler

All Known Implementing Classes:

AlexaSessionStateHandler, AWSDynamoStateHandler, AWSIotStateHandler, AWSS3StateHandler

public interface AlexaStateHandler

A state handler is an object which encapsulates persistence logic of your model states It comes in multiple flavours where each of the implementation is dedicated to a persistence store.

Method Summary

Modifier and Type	Method and Description
<TModel extends AlexaStateModel> TModel	createModel(Class<TModel> modelClass) Creates an instance of your model class and binds it to this handler.
<TModel extends AlexaStateModel> TModel	createModel(Class<TModel> modelClass, String id) Creates an instance of your model class and binds it to this handler.
<TModel extends AlexaStateModel> boolean	exists(Class<TModel> modelClass) Looks for a model in the persistence store.
<TModel extends AlexaStateModel> boolean	exists(Class<TModel> modelClass, AlexaScope scope) Looks for a model in the persistence store in a given scope.
<TModel extends AlexaStateModel> boolean	exists(Class<TModel> modelClass, String id) Looks for a model with given id in the persistence store.
<TModel extends AlexaStateModel> boolean	exists(Class<TModel> modelClass, String id, AlexaScope scope) Looks for a model with the given id in the persistence store in a given scope.
boolean	exists(String id) Looks for a state object with the given id.
boolean	exists(String id, AlexaScope scope) Looks for a state object with the given id in the given scope.
com.amazon.speech.speechlet.Session	getSession() Returns the Alexa Session object which was given to this handler.
<TModel extends AlexaStateModel> Optional<TModel>	readModel(Class<TModel> modelClass) Reads out the model from the persistence store of this handler.
<TModel extends AlexaStateModel> Optional<TModel>	readModel(Class<TModel> modelClass, String id) Reads out the model from the persistence store of this handler.
<TModel extends AlexaStateModel> Map<String,TModel>	readModels(Class<TModel> modelClass, Collection<String> ids) Reads out models from the persistence store of this handler.
Optional<AlexaStateObject>	readValue(String id) Reads a single object value from the persistence store.
Optional<AlexaStateObject>	readValue(String id, AlexaScope scope) Reads a single object value from the persistence store.
Map<String,AlexaStateObject>	readValues(Collection<String> ids) Reads multiple single object values from the persistence store.
Map<String,AlexaStateObject>	readValues(Collection<String> ids, AlexaScope scope) Reads multiple single object values from the persistence store in a specific scope.
Map<String,AlexaStateObject>	readValues(Map<String,AlexaScope> idsInScope) Reads multiple single object values from the persistence store in scopes.
void	removeModel(AlexaStateModel model) The given model will be removed from the persistence store.
void	removeModels(Collection<? extends AlexaStateModel> models) The given models will be removed from the persistence store.
void	removeValue(String id) Removes a single value state from the persistence store with the given key used when single value was written in store.
void	removeValues(Collection<String> ids) Removes multiple value states from the persistence store with given keys used when those values were written in store.
void	writeModel(AlexaStateModel model) The given model will be saved in the persistence store according to its AlexaStateSave-annotations.
void	writeModels(Collection<? extends AlexaStateModel> models) The given models will be saved in the persistence store according to their AlexaStateSave-annotations.
void	writeValue(AlexaStateObject stateObject) The value of a given state object will be saved with its id in the persistence store.
void	writeValue(String id, Object value) The given value will be saved with the given id in the persistence store.
void	writeValue(String id, Object value, AlexaScope scope) The given value will be saved with the given id in the persistence store.
void	writeValues(Collection<? extends AlexaStateObject> stateObjects) Values of given state objects will be saved with their ids in the persistence store.

Method Detail

getSession

com.amazon.speech.speechlet.Session getSession()

Returns the Alexa Session object which was given to this handler. This is where state of all models are written to and read from.

Returns:

Alexa Session object

createModel

<TModel extends AlexaStateModel> TModel createModel(Class<TModel> modelClass)

Creates an instance of your model class and binds it to this handler. Thus you can manage state directly on or in your model without referencing the handler anymore (e.g. AlexaStateModel.saveState() or AlexaStateModel.removeState()) This really much does the same as what you can achieve with AlexaStateModelFactory.createModel(Class, AlexaStateHandler). Of course you can initialize your models with its own constructor but make sure you setHandler() before calling aforementioned methods of this model. By using this method you are not assigning an id to the model. Your model behaves like a singleton within its AlexaScope (Session, User or Application) and is overridden on AlexaStateModel.saveState() if already existent.

Type Parameters:

TModel - type derived from AlexaStateModel

Parameters:

modelClass - type of your model you want to initialize. Model has to derive from AlexaStateModel

Returns:

Fresh instance of a model

createModel

<TModel extends AlexaStateModel> TModel createModel(Class<TModel> modelClass,
                                                    String id)

Creates an instance of your model class and binds it to this handler. Thus you can manage state directly on or in your model without referencing the handler anymore (e.g. AlexaStateModel.saveState() or AlexaStateModel.removeState()) This really much does the same as what you can achieve with AlexaStateModelFactory.createModel(Class, AlexaStateHandler). Of course you can initialize your models with its own constructor but make sure you AlexaStateModel.setHandler(AlexaStateHandler) before calling aforementioned methods of this model. By using this method you will assign an id to the model. From now on this id is used to read and write to the persistence store associated with the handler. It gives you freedom to have more than one of a kind of your model within its AlexaScope (Session, User, Application)

Type Parameters:

TModel - type derived from AlexaStateModel

Parameters:

modelClass - type of your model you want to initialize. Model has to derive from AlexaStateModel

id - An id unique within a model's AlexaScope. If a model with this id is already existing in the persistence store it will be overridden on AlexaStateModel.saveState().

Returns:

Fresh instance of a model

writeModel

void writeModel(AlexaStateModel model)
         throws AlexaStateException

The given model will be saved in the persistence store according to its AlexaStateSave-annotations. If you set up an Id for the model it will be accessible with it on later reads to the handler.

Parameters:

model - Your model which needs to be a type of AlexaStateModel

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

writeModels

void writeModels(Collection<? extends AlexaStateModel> models)
          throws AlexaStateException

The given models will be saved in the persistence store according to their AlexaStateSave-annotations. If you set up an Id for the model it will be accessible with it on later reads to the handler. If you have multiple models to save always prefer this method as it tries to batch process the models so it reduces the number of write-transactions to one.

Parameters:

models - list of models to save state

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

writeValue

void writeValue(String id,
                Object value)
         throws AlexaStateException

The given value will be saved with the given id in the persistence store. Without giving it a scope the handler will save state of the given object in Alexa session (Scope = Session)

Parameters:

id - the key used when writing value to the store

value - the actual object whose value will be saved

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

writeValue

void writeValue(String id,
                Object value,
                AlexaScope scope)
         throws AlexaStateException

The given value will be saved with the given id in the persistence store. Keep in mind that for the AlexaSessionStateHandler USER and APPLICATION scope cannot be served. In that case the value will be saved to Alexa session and will not persist permanently.

Parameters:

id - the key used when writing value to the store

value - the actual object whose value will be saved

scope - the scope the value is saved

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

writeValue

void writeValue(AlexaStateObject stateObject)
         throws AlexaStateException

The value of a given state object will be saved with its id in the persistence store. Keep in mind that for the AlexaSessionStateHandler USER and APPLICATION scope cannot be served. In that case the value will be saved to Alexa session and will not persist permanently.

Parameters:

stateObject - the state object to write to the persistence store

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

writeValues

void writeValues(Collection<? extends AlexaStateObject> stateObjects)
          throws AlexaStateException

Values of given state objects will be saved with their ids in the persistence store. Keep in mind that for the AlexaSessionStateHandler USER and APPLICATION scope cannot be served. In that case the value will be saved to Alexa session and will not persist permanently.

Parameters:

stateObjects - the state objects to write to the persistence store

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

removeModel

void removeModel(AlexaStateModel model)
          throws AlexaStateException

The given model will be removed from the persistence store. If it's not existing in the store nothing happens. Be aware of the Id set in the model as the removal will only affect the model with this id.

Parameters:

model - Your model which needs to be a type of AlexaStateModel

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

removeModels

void removeModels(Collection<? extends AlexaStateModel> models)
           throws AlexaStateException

The given models will be removed from the persistence store. If one of them is not existing in the store nothing happens. Be aware of the Id set in the models as the removal will only affect the model with its id.

Parameters:

models - Your models which need to be a type of AlexaStateModel

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

removeValue

void removeValue(String id)
          throws AlexaStateException

Removes a single value state from the persistence store with the given key used when single value was written in store. You could also use this method to remove a model. In that case be sure you provide the attribute-key of the model - not its id.

Parameters:

id - the key of a single value object whose state you want to remove from the store.

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

removeValues

void removeValues(Collection<String> ids)
           throws AlexaStateException

Removes multiple value states from the persistence store with given keys used when those values were written in store. You could also use this method to remove models. In that case be sure you provide the attributeKey of those models - not their id.

Parameters:

ids - the keys of single value objects whose state you want to remove from the store.

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

readModel

<TModel extends AlexaStateModel> Optional<TModel> readModel(Class<TModel> modelClass)
                                                     throws AlexaStateException

Reads out the model from the persistence store of this handler. Depending on the AlexaScopes configured in the AlexaStateSave annotations it will possibly collect data from more than one persistence store. (most likely from the Alexa session and maybe from the permanent persistence store associated with this handler. You are not providing an id with this call. Thus it will look for the single representative without an id.

Type Parameters:

TModel - Type derived from AlexaStateModel

Parameters:

modelClass - Type of the model you would like to read out. It needs to be of type AlexaStateModel.

Returns:

A model matching the given type and augmented with all the attributes found in the persistence store.

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

readModel

<TModel extends AlexaStateModel> Optional<TModel> readModel(Class<TModel> modelClass,
                                                            String id)
                                                     throws AlexaStateException

Reads out the model from the persistence store of this handler. Depending on the AlexaScopes configured in the AlexaStateSave annotations it will possibly collect data from more than one persistence store. (most likely from the Alexa session and maybe from the permanent persistence store associated with this handler. You are providing an id with this call. If you never saved the model with this id in the store you won't get anything.

Type Parameters:

TModel - Type derived from AlexaStateModel

Parameters:

modelClass - Type of the model you would like to read out. It needs to be of type AlexaStateModel.

id - The id of an existing instance of your model in the persistence store.

Returns:

A model matching the given type and id. Augmented with all the attributes found in the persistence store.

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

readModels

<TModel extends AlexaStateModel> Map<String,TModel> readModels(Class<TModel> modelClass,
                                                               Collection<String> ids)
                                                        throws AlexaStateException

Reads out models from the persistence store of this handler. Depending on the AlexaScopes configured in the AlexaStateSave annotations it will possibly collect data from more than one persistence store. (most likely from the Alexa session and maybe from the permanent persistence store associated with this handler.) You are providing ids with this call. If you never saved any model with one of the ids in the store you won't get them.

Type Parameters:

TModel - Type derived from AlexaStateModel

Parameters:

modelClass - Type of the model you would like to read out. It needs to be of type AlexaStateModel.

ids - Collection of ids of existing instances of your model in the persistence store. If you provide ids of non-existing items they just won't show up in the returned map.

Returns:

Map of ids from your input list of ids pointing to models that were found in the persistence store. Augmented with all the attributes found in the persistence store.

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

readValue

Optional<AlexaStateObject> readValue(String id)
                              throws AlexaStateException

Reads a single object value from the persistence store. If no scope is provided this method will always look for the value in Alexa session by default (Scope = Session). If you want to check existence of a state model keep in mind its id is the attribute-key of the model object, not the id you provided. The attribute-key derives from the model-id.

Parameters:

id - id of a state-object whose state you want to read from the store.

Returns:

the value of a state object with the given id. Empty, if not existent.

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

readValue

Optional<AlexaStateObject> readValue(String id,
                                     AlexaScope scope)
                              throws AlexaStateException

Reads a single object value from the persistence store. If you want to check existence of a state model keep in mind its id is the attribute-key of the model object, not the id you provided. The attribute-key derives from the model-id.

Parameters:

id - id of a state-object whose state you want to read from the store.

scope - read state-object in that scope.

Returns:

the value of a state object with the given id. Empty, if not existent.

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

readValues

Map<String,AlexaStateObject> readValues(Collection<String> ids)
                                 throws AlexaStateException

Reads multiple single object values from the persistence store. If no scope is provided this method will always look for values in Alexa session by default (Scope = Session). If you want to check existence of a state model keep in mind its id is the attribute-key of the model object, not the id you provided. The attribute-key derives from the model-id.

Parameters:

ids - ids of state-objects whose state you want to read from the store.

Returns:

map of state-objects found in the store where key is the object-id. State-objects which were not found in the store will be missing in that map.

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

readValues

Map<String,AlexaStateObject> readValues(Collection<String> ids,
                                        AlexaScope scope)
                                 throws AlexaStateException

Reads multiple single object values from the persistence store in a specific scope. If you want to check existence of a state model keep in mind its id is the attribute-key of the model object, not the id you provided. The attribute-key derives from the model-id.

Parameters:

ids - ids of state-objects whose state you want to read from the store.

scope - read state-objects in that scope.

Returns:

map of state-objects found in the store where key is the object-id. State-objects which were not found in the store will be missing in that map.

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

readValues

Map<String,AlexaStateObject> readValues(Map<String,AlexaScope> idsInScope)
                                 throws AlexaStateException

Reads multiple single object values from the persistence store in scopes. If you want to check existence of a state model keep in mind its id is the attribute-key of the model object, not the id you provided. The attribute-key derives from the model-id.

Parameters:

idsInScope - ids with scope of state-objects whose state you want to read from the store.

Returns:

map of state-objects found in the store where key is the object-id. State-objects which were not found in the store will be missing in that map.

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

exists

<TModel extends AlexaStateModel> boolean exists(Class<TModel> modelClass)
                                         throws AlexaStateException

Looks for a model in the persistence store. As this method does not take an id it looks for the static model instance which was written over the handler without giving it an id. If no scope is provided this method will always look for the model in Alexa session by default (Scope = Session)

Type Parameters:

TModel - Type derived from AlexaStateModel

Parameters:

modelClass - Type of the model you would like to check for existence. It needs to be of type AlexaStateModel.

Returns:

True, if model exists

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

exists

<TModel extends AlexaStateModel> boolean exists(Class<TModel> modelClass,
                                                String id)
                                         throws AlexaStateException

Looks for a model with given id in the persistence store. If no scope is provided this method will always look for the model in Alexa session by default (Scope = Session)

Type Parameters:

TModel - Type derived from AlexaStateModel

Parameters:

modelClass - Type of the model you would like to check for existence. It needs to be of type AlexaStateModel.

id - the id of a model

Returns:

True, if model exists

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

exists

<TModel extends AlexaStateModel> boolean exists(Class<TModel> modelClass,
                                                AlexaScope scope)
                                         throws AlexaStateException

Looks for a model in the persistence store in a given scope. As this method does not take an id it looks for the static model instance which was written over the handler without giving it an id.

Type Parameters:

TModel - Type derived from AlexaStateModel

Parameters:

modelClass - Type of the model you would like to check for existence. It needs to be of type AlexaStateModel.

scope - scope in which to test existence of model

Returns:

True, if model exists in scope

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

exists

<TModel extends AlexaStateModel> boolean exists(Class<TModel> modelClass,
                                                String id,
                                                AlexaScope scope)
                                         throws AlexaStateException

Looks for a model with the given id in the persistence store in a given scope.

Type Parameters:

TModel - Type derived from AlexaStateModel

Parameters:

modelClass - Type of the model you would like to check for existence. It needs to be of type AlexaStateModel.

id - the id of a model

scope - scope in which to test existence of model

Returns:

True, if model exists in scope

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

exists

boolean exists(String id)
        throws AlexaStateException

Looks for a state object with the given id. If no scope is provided this method will always look for the model in Alexa session by default (Scope = Session). If you want to check existence of a state model keep in mind its id is the attribute-key of the model object, not the id you provided. The attribute-key derives from the model-id.

Parameters:

id - id of a state-object whose existence you want to be checked in the store.

Returns:

True, if state object exists in the store

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model

exists

boolean exists(String id,
               AlexaScope scope)
        throws AlexaStateException

Looks for a state object with the given id in the given scope. If you want to check existence of a state model keep in mind its id is the attribute-key of the model object, not the id you provided. The attribute-key derives from the model-id.

Parameters:

id - id of a state-object whose existence you want to be checked in the store.

scope - look for state-object in that scope.

Returns:

True, if state object exists in that scope

Throws:

AlexaStateException - Wraps all inner exceptions and gives you context related to handler and model