com.netflix.msl.msg
Class MessageServiceTokenBuilder

java.lang.Object
  com.netflix.msl.msg.MessageServiceTokenBuilder

public class MessageServiceTokenBuilder
extends Object

A message service token builder provides methods for intelligently manipulating the primary and peer service tokens that will be included in a message.

There are two categories of service tokens: primary and peer.

• Primary service tokens are associated with the primary master token and peer user ID token, and are the only category of service token to appear in trusted network mode. Primary service tokens are also used in peer-to-peer mode.
• Peer service tokens are associated with the peer master token and peer user ID token and only used in peer-to-peer mode.

There are three levels of service token binding.

• Unbound service tokens may be freely moved between entities and users.
• Master token bound service tokens must be accompanied by a master token that they are bound to and will be rejected if sent with a different master token or without a master token. This binds a service token to a specific entity.
• User ID token bound service tokens must be accompanied by a user ID token that they are bound to and will be rejected if sent with a different user or used without a user ID token. This binds a service token to a specific user and by extension a specific entity.

Constructor Summary

MessageServiceTokenBuilder(MslContext ctx, MessageContext msgCtx, com.netflix.msl.msg.MessageBuilder builder)
Create a new message service token builder with the provided MSL and message contexts and message builder.

Method Summary

boolean	addMasterBoundPeerServiceToken(String name, byte[] data, boolean encrypt, MslConstants.CompressionAlgorithm compressionAlgo) Adds a new master token bound peer service token to the message, replacing any existing peer service token with the same name.
boolean	addMasterBoundPrimaryServiceToken(String name, byte[] data, boolean encrypt, MslConstants.CompressionAlgorithm compressionAlgo) Adds a new master token bound primary service token to the message, replacing any existing primary service token with the same name.
boolean	addPeerServiceToken(ServiceToken serviceToken) Adds a peer service token to the message, replacing any existing peer service token with the same name.
boolean	addPrimaryServiceToken(ServiceToken serviceToken) Adds a primary service token to the message, replacing any existing primary service token with the same name.
boolean	addUnboundPeerServiceToken(String name, byte[] data, boolean encrypt, MslConstants.CompressionAlgorithm compressionAlgo) Adds a new unbound peer service token to the message, replacing any existing peer service token with the same name.
boolean	addUnboundPrimaryServiceToken(String name, byte[] data, boolean encrypt, MslConstants.CompressionAlgorithm compressionAlgo) Adds a new unbound primary service token to the message, replacing any existing primary service token with the same name.
boolean	addUserBoundPeerServiceToken(String name, byte[] data, boolean encrypt, MslConstants.CompressionAlgorithm compressionAlgo) Adds a new user ID token bound peer service token to the message, replacing any peer existing service token with the same name.
boolean	addUserBoundPrimaryServiceToken(String name, byte[] data, boolean encrypt, MslConstants.CompressionAlgorithm compressionAlgo) Adds a new user ID token bound primary service token to the message, replacing any existing primary service token with the same name.
boolean	deletePeerServiceToken(String name) Mark a peer service token for deletion, if it exists.
boolean	deletePrimaryServiceToken(String name) Mark a primary service token for deletion, if it exists.
boolean	excludePeerServiceToken(String name) Exclude a peer service token from the message.
boolean	excludePrimaryServiceToken(String name) Exclude a primary service token from the message.
Set<ServiceToken>	getPeerServiceTokens()
Set<ServiceToken>	getPrimaryServiceTokens()
boolean	isPeerMasterTokenAvailable()
boolean	isPeerUserIdTokenAvailable()
boolean	isPrimaryMasterTokenAvailable() Returns true if the message has a primary master token available for adding master-bound primary service tokens.
boolean	isPrimaryUserIdTokenAvailable()

Methods inherited from class java.lang.Object

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

Constructor Detail

MessageServiceTokenBuilder

public MessageServiceTokenBuilder(MslContext ctx,
                                  MessageContext msgCtx,
                                  com.netflix.msl.msg.MessageBuilder builder)

Create a new message service token builder with the provided MSL and message contexts and message builder.

Parameters:

ctx - MSL context.

msgCtx - message context.

builder - message builder for message being built.

Method Detail

isPrimaryMasterTokenAvailable

public boolean isPrimaryMasterTokenAvailable()

Returns true if the message has a primary master token available for adding master-bound primary service tokens.

Returns:

true if the message has a primary master token.

isPrimaryUserIdTokenAvailable

public boolean isPrimaryUserIdTokenAvailable()

Returns:

true if the message has a primary user ID token.

isPeerMasterTokenAvailable

public boolean isPeerMasterTokenAvailable()

Returns:

true if the message has a peer master token.

isPeerUserIdTokenAvailable

public boolean isPeerUserIdTokenAvailable()

Returns:

true if the message has a peer user ID token.

getPrimaryServiceTokens

public Set<ServiceToken> getPrimaryServiceTokens()

Returns:

the unmodifiable set of primary service tokens that will be included in the built message.

getPeerServiceTokens

public Set<ServiceToken> getPeerServiceTokens()

Returns:

the unmodifiable set of peer service tokens that will be included in the built message.

addPrimaryServiceToken

public boolean addPrimaryServiceToken(ServiceToken serviceToken)
                               throws MslMessageException

Adds a primary service token to the message, replacing any existing primary service token with the same name.

Parameters:

serviceToken - primary service token.

Returns:

true if the service token was added, false if the service token is bound to a master token or user ID token and the message does not have the same token.

Throws:

MslMessageException - if the service token serial numbers do not match the primary master token or primary user ID token of the message being built.

addPeerServiceToken

public boolean addPeerServiceToken(ServiceToken serviceToken)
                            throws MslMessageException

Adds a peer service token to the message, replacing any existing peer service token with the same name.

Parameters:

serviceToken - peer service token.

Returns:

true if the service token was added, false if the service token is bound to a master token or user ID token and the message does not have the same token.

Throws:

MslMessageException - if the service token serial numbers do not match the peer master token or peer user ID token of the message being built.

addUnboundPrimaryServiceToken

public boolean addUnboundPrimaryServiceToken(String name,
                                             byte[] data,
                                             boolean encrypt,
                                             MslConstants.CompressionAlgorithm compressionAlgo)
                                      throws MslEncodingException,
                                             MslCryptoException,
                                             MslException

Adds a new unbound primary service token to the message, replacing any existing primary service token with the same name.

Parameters:

name - service token name.

data - service token data.

encrypt - true if the service token data should be encrypted.

compressionAlgo - the compression algorithm. May be null for no compression.

Returns:

true if the service token was added, false if there is no crypto context found for this service token.

Throws:

MslCryptoException - if there is an error encrypting or signing the token data.

MslEncodingException - if there is an error encoding the JSON data.

MslException - if there is an error compressing the data.

addUnboundPeerServiceToken

public boolean addUnboundPeerServiceToken(String name,
                                          byte[] data,
                                          boolean encrypt,
                                          MslConstants.CompressionAlgorithm compressionAlgo)
                                   throws MslEncodingException,
                                          MslCryptoException,
                                          MslException

Adds a new unbound peer service token to the message, replacing any existing peer service token with the same name.

Parameters:

name - service token name.

data - service token data.

encrypt - true if the service token data should be encrypted.

compressionAlgo - the compression algorithm. May be null for no compression.

Returns:

true if the service token was added, false if there is no crypto context found for this service token.

Throws:

MslCryptoException - if there is an error encrypting or signing the token data.

MslEncodingException - if there is an error encoding the JSON data.

MslException - if there is an error compressing the data.

addMasterBoundPrimaryServiceToken

public boolean addMasterBoundPrimaryServiceToken(String name,
                                                 byte[] data,
                                                 boolean encrypt,
                                                 MslConstants.CompressionAlgorithm compressionAlgo)
                                          throws MslEncodingException,
                                                 MslCryptoException,
                                                 MslException

Adds a new master token bound primary service token to the message, replacing any existing primary service token with the same name.

Parameters:

name - service token name.

data - service token data.

encrypt - true if the service token data should be encrypted.

compressionAlgo - the compression algorithm. May be null for no compression.

Returns:

true if the service token was added, false if there is no crypto context found for this service token or the message does not have a primary master token.

Throws:

MslCryptoException - if there is an error encrypting or signing the token data.

MslEncodingException - if there is an error encoding the JSON data.

MslException - if there is an error compressing the data.

addMasterBoundPeerServiceToken

public boolean addMasterBoundPeerServiceToken(String name,
                                              byte[] data,
                                              boolean encrypt,
                                              MslConstants.CompressionAlgorithm compressionAlgo)
                                       throws MslEncodingException,
                                              MslCryptoException,
                                              MslException

Adds a new master token bound peer service token to the message, replacing any existing peer service token with the same name.

Parameters:

name - service token name.

data - service token data.

encrypt - true if the service token data should be encrypted.

compressionAlgo - the compression algorithm. May be null for no compression.

Returns:

true if the service token was added, false if there is no crypto context found for this service token or the message does not have a peer master token.

Throws:

MslCryptoException - if there is an error encrypting or signing the token data.

MslEncodingException - if there is an error encoding the JSON data.

MslException - if there is an error compressing the data.

addUserBoundPrimaryServiceToken

public boolean addUserBoundPrimaryServiceToken(String name,
                                               byte[] data,
                                               boolean encrypt,
                                               MslConstants.CompressionAlgorithm compressionAlgo)
                                        throws MslEncodingException,
                                               MslCryptoException,
                                               MslException

Adds a new user ID token bound primary service token to the message, replacing any existing primary service token with the same name.

Parameters:

name - service token name.

data - service token data.

encrypt - true if the service token data should be encrypted.

compressionAlgo - the compression algorithm. May be null for no compression.

Returns:

true if the service token was added, false if there is no crypto context found for this service token or the message does not have a primary user ID token.

Throws:

MslCryptoException - if there is an error encrypting or signing the token data.

MslEncodingException - if there is an error encoding the JSON data.

MslException - if there is an error compressing the data.

addUserBoundPeerServiceToken

public boolean addUserBoundPeerServiceToken(String name,
                                            byte[] data,
                                            boolean encrypt,
                                            MslConstants.CompressionAlgorithm compressionAlgo)
                                     throws MslEncodingException,
                                            MslCryptoException,
                                            MslException

Adds a new user ID token bound peer service token to the message, replacing any peer existing service token with the same name.

Parameters:

name - service token name.

data - service token data.

encrypt - true if the service token data should be encrypted.

compressionAlgo - the compression algorithm. May be null for no compression.

Returns:

true if the service token was added, false if there is no crypto context found for this service token or the message does not have a peer user ID token.

Throws:

MslCryptoException - if there is an error encrypting or signing the token data.

MslEncodingException - if there is an error encoding the JSON data.

MslException - if there is an error compressing the data.

excludePrimaryServiceToken

public boolean excludePrimaryServiceToken(String name)

Exclude a primary service token from the message.

The service token will not be sent in the built message. This is not the same as requesting the remote entity delete a service token.

Parameters:

name - service token name.

Returns:

true if the service token was found and therefore removed.

excludePeerServiceToken

public boolean excludePeerServiceToken(String name)

Exclude a peer service token from the message.

The service token will not be sent in the built message. This is not the same as requesting the remote entity delete a service token.

Parameters:

name - service token name.

Returns:

true if the peer service token was found and therefore removed.

deletePrimaryServiceToken

public boolean deletePrimaryServiceToken(String name)

Mark a primary service token for deletion, if it exists.

The service token will be sent in the built message with an empty value. This is not the same as requesting that a service token be excluded from the message.

Parameters:

name - service token name.

Returns:

true if the service token exists and was marked for deletion.

deletePeerServiceToken

public boolean deletePeerServiceToken(String name)

Mark a peer service token for deletion, if it exists.

The service token will be sent in the built message with an empty value. This is not the same as requesting that a service token be excluded from the message.

Parameters:

name - service token name.

Returns:

true if the peer service token exists and was marked for deletion.