com.sas.entities
Interface RemoteBaseEntityInterface

All Superinterfaces:

java.rmi.Remote, RemoteBaseEntityValueInterface, com.sas.RemoteObjectInterface

All Known Subinterfaces:

EntityInterface, RemoteEntityInterface

All Known Implementing Classes:

Entity, RemoteEntity

public interface RemoteBaseEntityInterface
extends RemoteBaseEntityValueInterface

RemoteBaseEntityInterface extends the functionality of RemoteBaseEntityValueInterface. It provides methods for bulk access of attributes, removing attributes, as well as obtaining a list of attribute names associated with the Entity.

Bulk Access of Attributes

Bulk access of attributes is very useful when Entities are distributed objects: rather than perform 10 separate getAttribute calls, you can construct a bulk accessor property bag that contains the 10 attribute names, then perform one (remote) method call to get the values. This works whether the specific Entity class stores the values as attribute/value pairs in the internal Entity map, or if the values are stored as explicit instance variables and are accessed with explicit property set/get methods such as getName()/setName(). The RemoteEntity class uses JavaBeans introspection to find the property accessor methods automatically.

For example, consider a class named Person which extends RemoteEntity and has attributes givenName, surname, nameSuffix, namePrefix which each have access methods (type-based attributes). For an instance of Person, the application may also store an attribute named numDependents by invoking

    person.setAttribute("numDependents", new Integer(numDependents));
 

Later, a separate part of the application may wish to retrieve all these attributes in one bulk accessor call:

 HashMap query = new HashMap()
 query.put("namePrefix", null);
 query.put("givenName", null);
 query.put("surname", null);
 query.put("namesuffix", null);
 query.put("numDependents", null);
 query = person.getAttributes(query);
 

To satisfy the query, the Entity will look at the requested attributes. If an attribute has an accessor method (like getSurname() or getNamePrefix()), the Entity will invoke the accessor method to retrieve the attribute value. Otherwise, it is read from an internal map of property state.

Entities may be accessed remotely, thus all methods may throw RemoteException.

Method Summary

boolean	containsAttributeNamed(java.lang.String name) Test if this entity contains an attribute of a specified name.
java.lang.Object	getAttribute(java.lang.String attributeName, java.lang.Object defaultValue) Get a value of an attribute from the entity, or return a default value if it does not exist.
java.util.Map	getAttributes(java.util.Map query) Perform a bulk value get on this entity.
java.lang.String	getStringAttribute(java.lang.String attributeName, java.lang.String defaultValue) Get a string value of an attribute from an entity.
java.lang.String[]	listAttributeNames() Return an array of the attribute names on this entity.
void	removeAllAttributes() Remove all attributes from this entity.
void	removeAttribute(java.lang.String attributeName) Remove an attribute from this entity if the attribute is an instance-based attribute.
void	setAttributes(java.util.Map update) Perform a bulk attribute set on this entity.

Methods inherited from interface com.sas.entities.RemoteBaseEntityValueInterface

getAttribute, setAttribute

Method Detail

setAttributes

void setAttributes(java.util.Map update)
                   throws java.rmi.RemoteException,
                          AttributeSetException

Perform a bulk attribute set on this entity. This sets each attribute named in the update map

Parameters:

update - a set of name/value pairs to assign to the attributes of this entity

Throws:

AttributeSetException - if the AttributeType of a parameter is not compatible with a previous setting of the attribute OR an attribute has been designated as non-modifiable

java.rmi.RemoteException - if there was an IO error communicating with the Entity

getAttributes

java.util.Map getAttributes(java.util.Map query)
                            throws java.rmi.RemoteException

Perform a bulk value get on this entity. This gets each attribute named in the query map

Parameters:

query - a set of name/value pairs. This object is updated if the operation is performed locally.

Returns:

a map with names from the query and the values taken from this entity.

Throws:

java.rmi.RemoteException - if there was an IO error communicating with the Entity

containsAttributeNamed

boolean containsAttributeNamed(java.lang.String name)
                               throws java.rmi.RemoteException

Test if this entity contains an attribute of a specified name.

Parameters:

name - the attribute name to test

Returns:

true if this entity contains an attribute named name

Throws:

java.rmi.RemoteException - if there was an IO error communicating with the Entity

removeAttribute

void removeAttribute(java.lang.String attributeName)
                     throws java.rmi.RemoteException

Remove an attribute from this entity if the attribute is an instance-based attribute. You cannot remove type-based attributes from entities. After removing an instance-based attribute, containsAttributeNamed(String attributeName) will return false and getAttribute(String attributeName) will throw a NoSuchElementException

Parameters:

attributeName - the name of the attribute

Throws:

java.rmi.RemoteException - if there was an IO error communicating with the Entity

removeAllAttributes

void removeAllAttributes()
                         throws java.rmi.RemoteException

Remove all attributes from this entity.

Throws:

java.rmi.RemoteException - if there was an IO error communicating with the Entity

getStringAttribute

java.lang.String getStringAttribute(java.lang.String attributeName,
                                    java.lang.String defaultValue)
                                    throws java.rmi.RemoteException

Get a string value of an attribute from an entity. This method is an alias for (String) getAttribute(String attributeName).

Parameters:

attributeName - the name of the value.

defaultValue - a default value to return if the named value does not exist in this entity.

Returns:

the object associated with the attributeName, or the defaultValue if the entity does not contain an element for the specified attributeName.

Throws:

java.lang.ClassCastException - if the attribute value named by the attributeName is not a String value.

java.rmi.RemoteException - if there was an IO error communicating with the Entity

getAttribute

java.lang.Object getAttribute(java.lang.String attributeName,
                              java.lang.Object defaultValue)
                              throws java.rmi.RemoteException

Get a value of an attribute from the entity, or return a default value if it does not exist.

Parameters:

attributeName - the name of the value.

defaultValue - a default value to return if the named attribute does not exist in this entity.

Returns:

the object associated with the attributeName, or defaultValue if the entity does not contain an element for the specified attributeName.

Throws:

java.rmi.RemoteException - if there was an IO error communicating with the Entity

listAttributeNames

java.lang.String[] listAttributeNames()
                                      throws java.rmi.RemoteException

Return an array of the attribute names on this entity.

Throws:

java.rmi.RemoteException - if there was an IO error communicating with the Entity