com.kapowtech.robosuite.api.java.rql

Class RQLObjectBuilder

java.lang.Object

com.kapowtech.robosuite.api.java.rql.RQLObjectBuilder

public class RQLObjectBuilder
extends java.lang.Object

Used to build RQL Objects, typically for use as input objects to a robot. This class is provided as a convenience to the programmer, but is not needed to build RQLObjects.

RQLObject is an immutable class, as therefore it can be difficult to construct manually.

Chaining

The setAttribute methods in this class return a reference to the RQLObjectBuilder object itself, and are thus chainable in a way similar to the StringBuffer class.

Example of use

This shows how to build a rather complex set of query parameters, perhaps to search for biographical information. RQLObject userCredential = new RQLObjectBuilder("UserCredential"). setAttribute("username", "user42"). setAttribute("password", "secret").toRQLObject(); RQLResult result = RobotExecutor.execute( "library:/robots/bio-info.robot", userCredential);

The RQLObjectBuilder is itself mutable, but the RQLObjects it returns are inherently immutable.

Since:

1.1

See Also:

ExecuteRequestBuilder, RQLObject, Attribute, ExecuteRequestBuilder

Constructor Summary

Constructors

Constructor and Description
RQLObjectBuilder(RQLObject prototype) Creates a new RQLObjectBuilder that creates an RQLObject from a specified prototype.
RQLObjectBuilder(java.lang.String name) Creates a new RQLObjectBuilder that creates an RQLObject with the given name.

Method Summary

Modifier and Type	Method and Description
void	clearAttributes() Clears all attributes from the object being constructed.
java.lang.String	getName() Returns the name of the object under construction.
protected org.json.JSONObject	getOAuthJSON() Get the oauth information as JSON.
protected java.lang.String	getType() The type of RQL object (currently BASIC or OAUTH)
RQLObjectBuilder	setAttribute(Attribute attribute) Adds a new attribute to the RQL Object that is under construction.
RQLObjectBuilder	setAttribute(java.lang.String name, Binary value) Adds a new binary type attribute with the given name and value to the RQL Object that is under construction.
RQLObjectBuilder	setAttribute(java.lang.String name, boolean value) Adds a new boolean type attribute with the given name and value to the RQL Object that is under construction.
RQLObjectBuilder	setAttribute(java.lang.String name, byte[] value) Adds a new binary type attribute with the given name and value to the RQL Object that is under construction.
RQLObjectBuilder	setAttribute(java.lang.String name, char value) Adds a new character type attribute with the given name and value to the RQL Object that is under construction.
RQLObjectBuilder	setAttribute(java.lang.String name, java.util.Date value) Adds a new date type attribute with the given name and value to the RQL Object that is under construction.
RQLObjectBuilder	setAttribute(java.lang.String name, double value) Adds a new number type attribute with the given name and value to the RQL Object that is under construction.
RQLObjectBuilder	setAttribute(java.lang.String name, long value) Adds a new integer type attribute with the given name and value to the RQL Object that is under construction.
RQLObjectBuilder	setAttribute(java.lang.String name, java.lang.Object value) Adds a new attribute with the given name and value to the RQL Object under construction.
RQLObjectBuilder	setAttribute(java.lang.String name, java.lang.String value) Adds a new attribute with the given name and value to the RQL Object that is under construction.
RQLObjectBuilder	setAttributes(java.util.Map<java.lang.String,Attribute> attributes) Sets several attributes, initialized from the names and values of a java.util.Map.
void	setName(java.lang.String name) Returns the name of the object under construction.
org.json.JSONObject	toJSON() Translates this RQL object builder into JSON that can be used for calls to the tasks API on the Management Console
RQLObject	toRQLObject() Creates a new RQLObject initialized with the the values placed in this object.

Methods inherited from class java.lang.Object

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

Constructor Detail

RQLObjectBuilder

public RQLObjectBuilder(java.lang.String name)

Creates a new RQLObjectBuilder that creates an RQLObject with the given name.

Parameters:

name - the name of the new RQLObject to create.

Throws:

java.lang.NullPointerException - if the name parameter was null.

RQLObjectBuilder

public RQLObjectBuilder(RQLObject prototype)

Creates a new RQLObjectBuilder that creates an RQLObject from a specified prototype.

Parameters:

prototype - the prototype for the new RQLObject to create. The object being constructed will initially have the same name and attributes as the prototype. The prototype is not modified as a result of using it in this class, since it is immutable.

Throws:

java.lang.NullPointerException - if the prototype parameter was null.

Method Detail

getName

public java.lang.String getName()

Returns the name of the object under construction.

Returns:

the name of the model object.

setName

public void setName(java.lang.String name)

Returns the name of the object under construction.

Parameters:

name - the name of the model object.

Throws:

java.lang.NullPointerException - if the name parameter was null.

setAttribute

public RQLObjectBuilder setAttribute(java.lang.String name,
                                     java.lang.Object value)

Adds a new attribute with the given name and value to the RQL Object under construction. If the object under construction allready contains an attribute with the given name, it will be overwritten.

Parameters:

name - the name of the attribute

value - the attribute value, which must be a valid type. The attribute types are restricted to: java.lang.Boolean, java.util.Date, java.lang.Double, java.lang.Long, java.lang.Character, java.lang.String, and com.kapowtech.robosuite.api.java.rql.construct.Binary

Returns:

a reference to this object.

Throws:

java.lang.NullPointerException - if the name if the attribute is null.

InvalidAttributeTypeException - if the value argument is not an accepted type.

See Also:

Attribute, AttributeType

setAttribute

public RQLObjectBuilder setAttribute(java.lang.String name,
                                     java.lang.String value)

Adds a new attribute with the given name and value to the RQL Object that is under construction. If the object under construction already contains an attribute with the given name, it will be overwritten.

Parameters:

name - the name of the attribute

value - the attribute value.

Returns:

a reference to this object.

Throws:

java.lang.NullPointerException - if the name if the attribute is null.

InvalidAttributeTypeException - if the value argument is not an accepted type.

See Also:

Attribute, AttributeType

setAttribute

public RQLObjectBuilder setAttribute(java.lang.String name,
                                     long value)

Adds a new integer type attribute with the given name and value to the RQL Object that is under construction. If the object under construction allready contains an attribute with the given name, it will be overwritten.

Parameters:

name - the name of the attribute

value - a 64 bit signed integer value.

Returns:

a reference to this object.

See Also:

Attribute, AttributeType.INTEGER

setAttribute

public RQLObjectBuilder setAttribute(java.lang.String name,
                                     boolean value)

Adds a new boolean type attribute with the given name and value to the RQL Object that is under construction. If the object under construction allready contains an attribute with the given name, it will be overwritten.

Parameters:

name - the name of the attribute

value - a boolean value.

Returns:

a reference to this object.

See Also:

Attribute, AttributeType.BOOLEAN

setAttribute

public RQLObjectBuilder setAttribute(java.lang.String name,
                                     char value)

Adds a new character type attribute with the given name and value to the RQL Object that is under construction. If the object under construction allready contains an attribute with the given name, it will be overwritten.

Parameters:

name - the name of the attribute

value - a character value.

Returns:

a reference to this object.

See Also:

Attribute, AttributeType.CHARACTER

setAttribute

public RQLObjectBuilder setAttribute(java.lang.String name,
                                     double value)

Adds a new number type attribute with the given name and value to the RQL Object that is under construction. If the object under construction allready contains an attribute with the given name, it will be overwritten.

Parameters:

name - the name of the attribute

value - a floating point value.

Returns:

a reference to this object.

See Also:

Attribute, AttributeType.NUMBER

setAttribute

public RQLObjectBuilder setAttribute(java.lang.String name,
                                     java.util.Date value)

Adds a new date type attribute with the given name and value to the RQL Object that is under construction. If the object under construction allready contains an attribute with the given name, it will be overwritten.

Parameters:

name - the name of the attribute

value - a date value.

Returns:

a reference to this object.

See Also:

Attribute, AttributeType.DATE

setAttribute

public RQLObjectBuilder setAttribute(java.lang.String name,
                                     Binary value)

Adds a new binary type attribute with the given name and value to the RQL Object that is under construction. If the object under construction allready contains an attribute with the given name, it will be overwritten.

Parameters:

name - the name of the attribute

value - a binary value (a sequence of bytes).

Returns:

a reference to this object.

See Also:

Attribute, AttributeType.BINARY

setAttribute

public RQLObjectBuilder setAttribute(java.lang.String name,
                                     byte[] value)

Adds a new binary type attribute with the given name and value to the RQL Object that is under construction. If the object under construction allready contains an attribute with the given name, it will be overwritten.

Parameters:

name - the name of the attribute

value - a binary value (a sequance of bytes). This method constructs a new Binary object from the bytes.

Returns:

a reference to this object.

See Also:

Attribute, AttributeType.BINARY

setAttribute

public RQLObjectBuilder setAttribute(Attribute attribute)

Adds a new attribute to the RQL Object that is under construction. If the object under construction allready contains an attribute with the given name, it will be overwritten.

Parameters:

attribute - the attribute to add.

Returns:

a reference to this object.

Throws:

java.lang.NullPointerException - if the attribute parameter was null.

See Also:

Attribute, AttributeType.BINARY

setAttributes

public RQLObjectBuilder setAttributes(java.util.Map<java.lang.String,Attribute> attributes)

Sets several attributes, initialized from the names and values of a java.util.Map.

This convenience method loops over the map entries, adding a new attribute for each. The name of the new attribute will be the entry's key, and the value will be the entry's value.

Parameters:

attributes - to set as a map

Returns:

a reference to this object.

Throws:

java.lang.NullPointerException - if the attributes parameter was null, or any of the keys in the map are null.

InvalidAttributeTypeException - if the value argument is not an accepted type.

See Also:

Map.Entry.getKey(), Map.Entry.getValue()

clearAttributes

public void clearAttributes()

Clears all attributes from the object being constructed.

getType

protected java.lang.String getType()

The type of RQL object (currently BASIC or OAUTH)

Returns:

the type of object as a string.

getOAuthJSON

protected org.json.JSONObject getOAuthJSON()

Get the oauth information as JSON.

Returns:

the oauth information.

toRQLObject

public RQLObject toRQLObject()

Creates a new RQLObject initialized with the the values placed in this object. The created object is immutable, and will not be changed, even if this builder is modified.

Returns:

an new RQLObject initialized with the the values placed in this object.

toJSON

public org.json.JSONObject toJSON()

Translates this RQL object builder into JSON that can be used for calls to the tasks API on the Management Console

Returns:

a JSONObject containing the