juglr
Class Box

java.lang.Object
  extended by juglr.Message
      extended by juglr.Box
All Implemented Interfaces:
java.io.Serializable

public class Box
extends Message
implements java.io.Serializable

Recommended Message class for general purpose messaging. A Box is a value container type that can hold one of:

Box instances serialize cleanly and efficiently over streams, and Juglr bundles the classes JSonBoxReader and JSonBoxParser for this purpose.

See Also:
JSonBoxReader, JSonBoxParser, Serialized Form

Nested Class Summary
static class Box.Type
          The allowed types for box values
static class Box.TypeException
          Thrown when invoking methods on a box of a type that does not admit the invoked method
 
Constructor Summary
Box(boolean val)
          Create a Box to hold a boolean
Box(Box.Type type)
          Create a Box to hold a value of type type
Box(double val)
          Create a Box to hold a double
Box(java.util.List<Box> val)
          Create a Box to hold a list of boxes
Box(long val)
          Create a Box to hold a long
Box(java.util.Map<java.lang.String,Box> val)
          Create a Box to hold a map of string keys to Box values
Box(java.lang.String val)
          Create a Box to hold a String
 
Method Summary
 Box add(boolean val)
          Add a child to a Box of LIST type.
 Box add(Box box)
          Add a child Box to a Box of LIST type.
 Box add(double val)
          Add a child to a Box of LIST type.
 Box add(java.util.List<Box> val)
          Add a child Box to a Box of LIST type.
 Box add(long val)
          Add a child to a Box of LIST type.
 Box add(java.util.Map<java.lang.String,Box> val)
          Add a child Box to a Box of LIST type.
 Box add(java.lang.String val)
          Add a child Box to a Box of LIST type.
 Box addAll(java.util.Collection<Box> boxes)
          Add a collection of child boxes to a box of LIST type.
 void checkType(Box.Type t)
          Assert that this Box is of type t and throw a Box.TypeException if it is not.
static void checkType(Box m, Box.Type t)
          Assert that the Box m is of type t and throw a Box.TypeException if it is not.
 boolean equals(java.lang.Object o)
           
 Box get(int index)
          Get the Box at index from a Box of LIST type.
 Box get(java.lang.String key)
          Retrieve a child Box with key key from a Box of MAP type.
 boolean getBoolean()
          Get the boolean which is contained in this Box of BOOLEAN type
 boolean getBoolean(int index)
           
 boolean getBoolean(java.lang.String key)
           
 boolean getBoolean(java.lang.String key, boolean defaultVal)
           
 double getFloat()
          Get the double which is contained in this Box of FLOAT type
 double getFloat(int index)
           
 double getFloat(java.lang.String key)
           
 double getFloat(java.lang.String key, double defaultVal)
           
 java.util.List<Box> getList()
          Get the List which is contained in this Box of LIST type
 java.util.List<Box> getList(int index)
           
 java.util.List<Box> getList(java.lang.String key)
           
 java.util.List<Box> getList(java.lang.String key, java.util.List<Box> defaultVal)
           
 long getLong()
          Get the long which is contained in this Box of INT type
 long getLong(int index)
           
 long getLong(java.lang.String key)
           
 long getLong(java.lang.String key, long defaultVal)
           
 java.util.Map<java.lang.String,Box> getMap()
          Get the Map which is contained in this Box of MAP type
 java.util.Map<java.lang.String,Box> getMap(int index)
           
 java.util.Map<java.lang.String,Box> getMap(java.lang.String key)
           
 java.util.Map<java.lang.String,Box> getMap(java.lang.String key, java.util.Map<java.lang.String,Box> defaultVal)
           
 java.lang.String getString()
          Get the String which is contained in this Box of STRING type
 java.lang.String getString(int index)
           
 java.lang.String getString(java.lang.String key)
           
 java.lang.String getString(java.lang.String key, java.lang.String defaultVal)
           
 Box.Type getType()
          Get the type of the value stored in the box
 Box.Type getType(int index)
          Get the value type of the box stored at position index of this list type box.
 Box.Type getType(java.lang.String key)
          Get the value type of the box stored with key key of this map type box.
 java.io.Serializable getVal()
          Get the raw value contained in this box
 boolean has(int index)
          Return true if index is within the range of the list contained in this box of LIST type
 boolean has(java.lang.String key)
          Check if this box of map type has a child for the key key
static Box newList()
          Create a Box that holds an empty list
static Box newMap()
          Create a Box that holds an empty map of string keys to Box values
 Box put(java.lang.String key, boolean val)
          Associate a value with key in box of MAP type.
 Box put(java.lang.String key, Box val)
          Associate a key String with a child Box inside a Box of LIST type.
 Box put(java.lang.String key, double val)
          Associate a value with key in box of MAP type.
 Box put(java.lang.String key, java.util.List<Box> val)
          Associate a value with key in box of MAP type.
 Box put(java.lang.String key, long val)
          Associate a value with key in box of MAP type.
 Box put(java.lang.String key, java.util.Map<java.lang.String,Box> val)
          Associate a value with key in box of MAP type.
 Box put(java.lang.String key, java.lang.String val)
          Associate a value with key in box of MAP type.
 Box putAll(java.util.Map<java.lang.String,Box> map)
          Import all key-value pairs from map into this Box (which must be of the MAP type).
 int size()
          Return the number of immediate child StructuredMessages of this Box
 byte[] toBytes()
          Return a newly allocated byte array containing this box as JSON encoded in the default system encoding.
 java.lang.String toString()
          String format the value contained in this box
 
Methods inherited from class juglr.Message
getReplyTo, getSender, setReplyTo
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Box

public Box(Box.Type type)
Create a Box to hold a value of type type

Parameters:
type - the value type to store in the box

Box

public Box(long val)
Create a Box to hold a long

Parameters:
val - the value to store in the box

Box

public Box(double val)
Create a Box to hold a double

Parameters:
val - the value to store in the box

Box

public Box(boolean val)
Create a Box to hold a boolean

Parameters:
val - the value to store in the box

Box

public Box(java.lang.String val)
Create a Box to hold a String

Parameters:
val - the value to store in the box

Box

public Box(java.util.List<Box> val)
Create a Box to hold a list of boxes

Parameters:
val - the value to store in the box

Box

public Box(java.util.Map<java.lang.String,Box> val)
Create a Box to hold a map of string keys to Box values

Parameters:
val - the value to store in the box
Method Detail

newList

public static Box newList()
Create a Box that holds an empty list

Returns:
a new box storing and empty list

newMap

public static Box newMap()
Create a Box that holds an empty map of string keys to Box values

Returns:
a box holding an empty map

getType

public Box.Type getType()
Get the type of the value stored in the box

Returns:
the type of the value stored in the box

getType

public Box.Type getType(int index)
Get the value type of the box stored at position index of this list type box.

Parameters:
index - the index into the list stored by this box
Returns:
the value type at position index of this box
Throws:
Box.TypeException - if this is not of type LIST

getType

public Box.Type getType(java.lang.String key)
Get the value type of the box stored with key key of this map type box.

Parameters:
key - check box with this key
Returns:
the value type for the child box corresponding to key
Throws:
Box.TypeException - if this is not of type MAP
java.lang.NullPointerException - if there is no box for key

has

public boolean has(java.lang.String key)
Check if this box of map type has a child for the key key

Parameters:
key - the key to check
Returns:
true if there is a box for the given key
Throws:
Box.TypeException - if this is not of type MAP
java.lang.NullPointerException - if there is no box for key

has

public boolean has(int index)
Return true if index is within the range of the list contained in this box of LIST type

Parameters:
index - the number to check
Returns:
true if and only if index is a valid index into the list

getVal

public java.io.Serializable getVal()
Get the raw value contained in this box

Returns:
the value within this box

add

public Box add(Box box)
Add a child Box to a Box of LIST type. This method always returns this.

Parameters:
box - the Box to append
Returns:
this
Throws:
Box.TypeException - if this box is not of type LIST

add

public Box add(long val)
Add a child to a Box of LIST type. This method always returns this.

Parameters:
val - the value to append
Returns:
this
Throws:
Box.TypeException - if this box is not of type LIST

add

public Box add(double val)
Add a child to a Box of LIST type. This method always returns this.

Parameters:
val - the value to append
Returns:
this
Throws:
Box.TypeException - if this box is not of type LIST

add

public Box add(boolean val)
Add a child to a Box of LIST type. This method always returns this.

Parameters:
val - the value to append
Returns:
this
Throws:
Box.TypeException - if this box is not of type LIST

add

public Box add(java.lang.String val)
Add a child Box to a Box of LIST type. This method always returns this.

Parameters:
val - the value to append
Returns:
this
Throws:
Box.TypeException - if this box is not of type LIST

add

public Box add(java.util.List<Box> val)
Add a child Box to a Box of LIST type. This method always returns this.

Parameters:
val - the list to append
Returns:
this
Throws:
Box.TypeException - if this box is not of type LIST

add

public Box add(java.util.Map<java.lang.String,Box> val)
Add a child Box to a Box of LIST type. This method always returns this.

Parameters:
val - the map to append
Returns:
this
Throws:
Box.TypeException - if this box is not of type LIST

addAll

public Box addAll(java.util.Collection<Box> boxes)
Add a collection of child boxes to a box of LIST type. This method always returns this.

Parameters:
boxes - the collection of Box instances to add
Returns:
this
Throws:
Box.TypeException - if this box is not of type LIST

put

public Box put(java.lang.String key,
               Box val)
Associate a key String with a child Box inside a Box of LIST type.

Parameters:
key - the key to add val under
val - the Box to associate with key
Returns:
this
Throws:
Box.TypeException - if this box is not of type MAP

put

public Box put(java.lang.String key,
               long val)
Associate a value with key in box of MAP type.

Parameters:
key - the key to associate val with
val - the value to insert
Returns:
this
Throws:
Box.TypeException - if this box is not of type MAP

put

public Box put(java.lang.String key,
               double val)
Associate a value with key in box of MAP type.

Parameters:
key - the key to associate val with
val - the value to insert
Returns:
this
Throws:
Box.TypeException - if this box is not of type MAP

put

public Box put(java.lang.String key,
               boolean val)
Associate a value with key in box of MAP type.

Parameters:
key - the key to associate val with
val - the value to insert
Returns:
this
Throws:
Box.TypeException - if this box is not of type MAP

put

public Box put(java.lang.String key,
               java.lang.String val)
Associate a value with key in box of MAP type.

Parameters:
key - the key to associate val with
val - the value to insert
Returns:
this
Throws:
Box.TypeException - if this box is not of type MAP

put

public Box put(java.lang.String key,
               java.util.List<Box> val)
Associate a value with key in box of MAP type.

Parameters:
key - the key to associate val with
val - the value to insert
Returns:
this
Throws:
Box.TypeException - if this box is not of type MAP

put

public Box put(java.lang.String key,
               java.util.Map<java.lang.String,Box> val)
Associate a value with key in box of MAP type.

Parameters:
key - the key to associate val with
val - the value to insert
Returns:
this
Throws:
Box.TypeException - if this box is not of type MAP

putAll

public Box putAll(java.util.Map<java.lang.String,Box> map)
Import all key-value pairs from map into this Box (which must be of the MAP type).

Parameters:
map - a
Returns:
this
Throws:
Box.TypeException - if this box is not of type MAP

getLong

public long getLong()
Get the long which is contained in this Box of INT type

Returns:
the value contained in the box
Throws:
Box.TypeException - if this box is not of type INT

getLong

public long getLong(int index)

getLong

public long getLong(java.lang.String key)

getLong

public long getLong(java.lang.String key,
                    long defaultVal)

getFloat

public double getFloat()
Get the double which is contained in this Box of FLOAT type

Returns:
the value contained in the box
Throws:
Box.TypeException - if this box is not of type FLOAT

getFloat

public double getFloat(int index)

getFloat

public double getFloat(java.lang.String key)

getFloat

public double getFloat(java.lang.String key,
                       double defaultVal)

getBoolean

public boolean getBoolean()
Get the boolean which is contained in this Box of BOOLEAN type

Returns:
the value contained in the box
Throws:
Box.TypeException - if this box is not of type BOOLEAN

getBoolean

public boolean getBoolean(int index)

getBoolean

public boolean getBoolean(java.lang.String key)

getBoolean

public boolean getBoolean(java.lang.String key,
                          boolean defaultVal)

getString

public java.lang.String getString()
Get the String which is contained in this Box of STRING type

Returns:
the value contained in the box
Throws:
Box.TypeException - if this box is not of type STRING

getString

public java.lang.String getString(int index)

getString

public java.lang.String getString(java.lang.String key)

getString

public java.lang.String getString(java.lang.String key,
                                  java.lang.String defaultVal)

getList

public java.util.List<Box> getList()
Get the List which is contained in this Box of LIST type

Returns:
the value contained in the box
Throws:
Box.TypeException - if this box is not of type LIST

getList

public java.util.List<Box> getList(int index)

getList

public java.util.List<Box> getList(java.lang.String key)

getList

public java.util.List<Box> getList(java.lang.String key,
                                   java.util.List<Box> defaultVal)

getMap

public java.util.Map<java.lang.String,Box> getMap()
Get the Map which is contained in this Box of MAP type

Returns:
the value contained in the box
Throws:
Box.TypeException - if this box is not of type MAP

getMap

public java.util.Map<java.lang.String,Box> getMap(int index)

getMap

public java.util.Map<java.lang.String,Box> getMap(java.lang.String key)

getMap

public java.util.Map<java.lang.String,Box> getMap(java.lang.String key,
                                                  java.util.Map<java.lang.String,Box> defaultVal)

get

public Box get(int index)
Get the Box at index from a Box of LIST type.

Parameters:
index - the index into the list from which to retrieve the child Box
Returns:
the Box at index

get

public Box get(java.lang.String key)
Retrieve a child Box with key key from a Box of MAP type.

Parameters:
key - the key for the child Box to look up
Returns:
the child Box or null

size

public int size()
Return the number of immediate child StructuredMessages of this Box

Returns:
The number of child boxes. This will be 0 for all Boxes that are not of the types MAP or LIST

checkType

public void checkType(Box.Type t)
Assert that this Box is of type t and throw a Box.TypeException if it is not.

Parameters:
t - the type that this Box must be

checkType

public static void checkType(Box m,
                             Box.Type t)
Assert that the Box m is of type t and throw a Box.TypeException if it is not.

Parameters:
m - the Box to check the type of
t - the type that this Box must be

equals

public boolean equals(java.lang.Object o)
Overrides:
equals in class java.lang.Object

toString

public java.lang.String toString()
String format the value contained in this box

Overrides:
toString in class java.lang.Object
Returns:
human readable and serialization-friendly string format of the box's value

toBytes

public byte[] toBytes()
Return a newly allocated byte array containing this box as JSON encoded in the default system encoding.

This method is slightly faster than toString().getBytes() in that it avoids the intermediate string representation of the box.

Returns:
a JSON data encoded in the default system encoding