com.buildforge.services.client.dbo
Class Collector

java.lang.Object
  extended by com.buildforge.services.client.dbo.Collector

public final class Collector
extends java.lang.Object

An object representing a collector within the Build Forge system. Collectors are assigned to servers, and they gather information from those servers that can later be used by selectors when determining which server should be used for running a step.

This class defines the collector itself. Precisely what information the collector will gather is determined by the properties that belong to it.

A full list of pre-defined, built-in properties that may be collected (such as NUM_CPU, MEM_FREE, etc.) can be obtained via getBuiltIns().


Field Summary
static java.lang.Class<Collector> CLASS
           
 
Constructor Summary
Collector(APIClientConnection conn)
          Define a new collector object.
 
Method Summary
 void addCollectorProperty(CollectorProperty prop)
          Adds a new property to this collector at the end of the property list.
 void addCollectorProperty(CollectorProperty prop, int index)
          Adds a new property to this collector at a specified index.
 Collector clone()
          Clones this Collector, complete with related CollectorProperties (also cloned), but clears the collector name (id) of the cloned object making it ready for a .create() call.
 CollectorProperty copyCollectorProperty(int fromIndex)
          Copies the property from the specified index and returns the copy for possible addition to another collector.
 CollectorProperty copyCollectorProperty(int fromIndex, int toIndex)
          Copies the property from the specified index and inserts the copy into the same collector's property list.
 Collector create()
          Creates a new collector, as defined by this object.
 void delete()
          Deletes this collector and all of its properties from the system.
static java.util.List<Collector> findAll(APIClientConnection conn)
          Finds all collectors that are defined within the system.
static Collector findById(APIClientConnection conn, java.lang.String collectorName)
          Retrieves a Collector by its unique identifier (name).
static java.lang.String[] getBuiltIns()
          Returns an array containing all the collector property names that correspond to built-in properties.
 java.lang.String getCollectorName()
          The name of this Collector.
 java.util.List<CollectorProperty> getProperties()
          Returns a copy of the list of Collector Properties.
 CollectorProperty getProperty(int index)
          Retrieves a collector property by its index into the current list of properties.
 CollectorProperty getProperty(java.lang.String propertyName)
          Retrieves a collector property by name.
 Collector moveCollectorProperty(int fromIndex, int toIndex)
          Moves a property from one index to another.
 CollectorProperty removeCollectorProperty(CollectorProperty property)
          Removes the specified property from the collector.
 CollectorProperty removeCollectorProperty(int index)
          Removes the specified property from the collector.
 CollectorProperty removeProperty(java.lang.String propertyName)
          Removes the first property with the specified property name from this collector.
 void setCollectorName(java.lang.String collectorId)
          Renames this collector.
 java.lang.String toString()
           
 Collector update()
          Updates this existing collector to use the updated values in this object.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

CLASS

public static final java.lang.Class<Collector> CLASS
Constructor Detail

Collector

public Collector(APIClientConnection conn)
Define a new collector object. The collector does not exist until after it has been created using the create() method.

Parameters:
conn - the services layer connection that the collector object should use when submitting requests
Method Detail

getBuiltIns

public static java.lang.String[] getBuiltIns()
Returns an array containing all the collector property names that correspond to built-in properties. The built-in properties are described in the enumeration that defines them.


findById

public static Collector findById(APIClientConnection conn,
                                 java.lang.String collectorName)
                          throws java.io.IOException,
                                 ServiceException
Retrieves a Collector by its unique identifier (name).

Parameters:
conn - the connection to use for this request
collectorName - the name of the collector to find
Returns:
the collector, or null if the requested collector could not be found.
Throws:
java.io.IOException
ServiceException

findAll

public static java.util.List<Collector> findAll(APIClientConnection conn)
                                         throws java.io.IOException,
                                                ServiceException
Finds all collectors that are defined within the system. The collectors are returned without its child properties. To retrieve them, user findById(APIClientConnection, String) to reload the individual collector of interest.

Parameters:
conn - the connection to use for this request
Returns:
a list of collectors
Throws:
java.io.IOException
ServiceException

create

public Collector create()
                 throws java.io.IOException,
                        ServiceException
Creates a new collector, as defined by this object. If this collector has any properties attached, then they are created, as well.

Restrictions: Requires Permission.AddCollector.

Returns:
the newly created collector
Throws:
java.io.IOException
ServiceException

delete

public void delete()
            throws java.io.IOException,
                   ServiceException
Deletes this collector and all of its properties from the system.

Restrictions: Requires Permission.DeleteCollector. The collector can not be included by another collector, nor can it be assigned to any server.

Throws:
java.io.IOException
ServiceException

update

public Collector update()
                 throws java.io.IOException,
                        ServiceException
Updates this existing collector to use the updated values in this object. Changes to its property values are NOT committed by this method; call CollectorProperty.update() on each of them, instead.

Restrictions: Requires Permission.EditCollector.

Returns:
this collector
Throws:
java.io.IOException
ServiceException

addCollectorProperty

public void addCollectorProperty(CollectorProperty prop)
                          throws java.io.IOException,
                                 ServiceException
Adds a new property to this collector at the end of the property list. If the collector object is already live, then this request is immediately sent to the server for approval.

Restrictions: Requires Permission.EditCollector if the collector object is already live.

Parameters:
prop - the property to add to the collector
Throws:
java.io.IOException
ServiceException

addCollectorProperty

public void addCollectorProperty(CollectorProperty prop,
                                 int index)
                          throws java.io.IOException,
                                 ServiceException
Adds a new property to this collector at a specified index. If the collector object is already live, then this request is immediately sent to the server for approval.

Restrictions: Requires Permission.EditCollector if the collector object is already live.

Parameters:
prop - the property to add to the collector
index - the 0-based index at which to insert the new property. If the specified value would place the new property at or beyond the end of the list, then it is placed at the end.
Throws:
java.io.IOException
ServiceException

moveCollectorProperty

public Collector moveCollectorProperty(int fromIndex,
                                       int toIndex)
                                throws java.io.IOException,
                                       ServiceException
Moves a property from one index to another. If the collector object is already live, then this request is immediately sent to the server for approval. The move is processed as a removal from fromIndex and an add at toIndex. For illustration purposes, consider the following scenario where moveCollectorProperty(1,3) is called:

Restrictions: Requires Permission.EditCollector if the collector object is already live.

Parameters:
fromIndex - the index of the property to move
toIndex - the new index of the property after it has been moved. If the new index is past the end of the list, then the property is moved to the end of the list, and if it is equal to fromIndex, then no action is taken.
Throws:
java.io.IOException
ServiceException

copyCollectorProperty

public CollectorProperty copyCollectorProperty(int fromIndex)
                                        throws ServiceException
Copies the property from the specified index and returns the copy for possible addition to another collector.

Parameters:
fromIndex - the index of the collector property to copy (0-based)
Returns:
the copied collector property
Throws:
ServiceException

copyCollectorProperty

public CollectorProperty copyCollectorProperty(int fromIndex,
                                               int toIndex)
                                        throws java.io.IOException,
                                               ServiceException
Copies the property from the specified index and inserts the copy into the same collector's property list.

Restrictions: Requires Permission.EditCollector if the collector object is already live.

Parameters:
fromIndex - the index of the property to move
toIndex - the new index of the property after it has been moved. If the new index is past the end of the list, then the property is moved to the end of the list, and if it is equal to fromIndex, then no action is taken.
Returns:
the copied collector property
Throws:
java.io.IOException
ServiceException

removeProperty

public CollectorProperty removeProperty(java.lang.String propertyName)
                                 throws ServiceException,
                                        java.io.IOException
Removes the first property with the specified property name from this collector.

Restrictions: Requires Permission.EditCollector if the collector object is already live.

Parameters:
propertyName - the name of the property to remove
Returns:
the property that was removed
Throws:
ServiceException
java.io.IOException

removeCollectorProperty

public CollectorProperty removeCollectorProperty(CollectorProperty property)
                                          throws ServiceException,
                                                 java.io.IOException
Removes the specified property from the collector.

Restrictions: Requires Permission.EditCollector if the collector object is already live.

Parameters:
property - The property to remove
Returns:
the property that was removed, or null if the specified property is null or does not belong to this collector
Throws:
ServiceException
java.io.IOException

removeCollectorProperty

public CollectorProperty removeCollectorProperty(int index)
                                          throws ServiceException,
                                                 java.io.IOException
Removes the specified property from the collector.

Restrictions: Requires Permission.EditCollector if the collector object is already live.

Parameters:
index - the 0-based index of the property to remove.
Returns:
the removed property
Throws:
ServiceException
java.io.IOException

clone

public Collector clone()
Clones this Collector, complete with related CollectorProperties (also cloned), but clears the collector name (id) of the cloned object making it ready for a .create() call.

Overrides:
clone in class java.lang.Object

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

getCollectorName

public java.lang.String getCollectorName()
The name of this Collector.


setCollectorName

public void setCollectorName(java.lang.String collectorId)
                      throws ServiceException,
                             java.io.IOException
Renames this collector. The rename does not take effect until update() is called. As when creating a collector, the collector name must be unique.

Parameters:
collectorName - the new name for this collector.
Throws:
ServiceException
java.io.IOException

getProperties

public java.util.List<CollectorProperty> getProperties()
Returns a copy of the list of Collector Properties. Changes to the collector properties themselves will be reflected in this object, but changes to the structure of the list will not.

Returns:
a copy of the current list of properties

getProperty

public CollectorProperty getProperty(java.lang.String propertyName)
Retrieves a collector property by name.

Parameters:
propertyName - the name of the property to find
Returns:
the collector property with the specified name, or null if no such property can be found

getProperty

public CollectorProperty getProperty(int index)
                              throws APIException
Retrieves a collector property by its index into the current list of properties.

Parameters:
index - The 0-based index of the collector property to retrieve from the list
Throws:
APIException

Index 
0 1 2 3 4 Comments
A B C D E Initial state
A C D E   First, the B property is removed from index 1
A C D B E Then, it is re-inserted at index 3