com.whitepages.proapi.data.entity

Interface Entity

All Known Subinterfaces:

Business, LegalEntity, Location, Person, Phone

All Known Implementing Classes:

BusinessImpl, BusinessProxy, EntityImpl, EntityProxy, LocationImpl, LocationProxy, PersonImpl, PersonProxy, PhoneImpl, PhoneProxy

public interface Entity

The root interface for all Entities (e.g. Person, Business, Phone, and Location).

The Whitepages API presents its data in a directed graph form, whereby:

• Each node is an Entity, and
• each Edge is an Association.

Entities contain data intrinsic to the entity, whereas associations contain data pertaining to the relationship between its source and destination entities

Properties

Entity properties are optionally filled in; factors include the query type and the API Key configuration. When a value is not available, its accessor is filled in with a null value, therefore it is a good idea to check the nullness of property values before using them.

Traversal

There are two ways to traverse the graph:

1. Explicit traversal through the association, and
2. Direct traversal to the associated entity.

The former is useful when information on the association is desired; however, one is often interested only in the associated entity itself, in which case direct traversal is clearer.

For example, the following two lines have the same effect:

 Person p1 = phone.getPersonAssociations().get(0).getPerson();
 Person p2 = phone.getPeople().get(0);
 p1 == p2 //is true
 
 

Careful readers of the above example will note that extra safety code is needed to check that the returned lists are non-null and non-empty before calling get().

Proxies

The complete entity graph, traversed to its full extent, would be incredibly large, thus, in practice, only a subset of this graph is presented in the Response. As a result, in some cases you may encounter associations whose nodes are not available to you. When this occurs, an appropriate EntityProxy instance is put into its place. To test if an entity is a proxy, use the isProxy() method.

Entity proxies satisfy the appropriate entity interface, returning null for all the values—acting as if the values were masked from you. The exception to this rule is the ID of the associated entity, which is always present on a proxy value.

To load an entity, call the load() method. This method will make a call to the remote service, fetching information for the associated entity ID. To test if a value has been loaded, the isLoaded() method may be used.

See Also:

Person, Business, Phone, Location, Association, EntityProxy

Method Summary

Methods

Modifier and Type	Method and Description
java.util.List<Association>	getAssociations() A convenience method for getting the concatenation of the association lists.
java.util.List<BusinessAssociation>	getBusinessAssociations()
java.util.List<Business>	getBusinesses()
java.util.List<Entity>	getEntities() A convenience method for getting the concatenation of the entity lists.
EntityId	getId()
java.util.List<LocationAssociation>	getLocationAssociations()
java.util.List<Location>	getLocations()
java.lang.String	getName() A standardized method for getting the primary, human readable, formatted String version of this entity.
java.util.List<Person>	getPeople()
java.util.List<PersonAssociation>	getPersonAssociations()
java.util.List<PhoneAssociation>	getPhoneAssociations()
java.util.List<Phone>	getPhones()
boolean	isLoaded() If the called on a proxy, return true only if the backing entity has been fetched.
boolean	isProxy() Returns true if this entity instance is a proxy instance.
void	load() Causes this instance to load its data by contacting the remote service and requesting information.

Method Detail

getId

EntityId getId()

getPersonAssociations

java.util.List<PersonAssociation> getPersonAssociations()

getBusinessAssociations

java.util.List<BusinessAssociation> getBusinessAssociations()

getLocationAssociations

java.util.List<LocationAssociation> getLocationAssociations()

getPhoneAssociations

java.util.List<PhoneAssociation> getPhoneAssociations()

getAssociations

java.util.List<Association> getAssociations()

A convenience method for getting the concatenation of the association lists.

Returns:

Concatenated list of all associations.

getPeople

java.util.List<Person> getPeople()

getBusinesses

java.util.List<Business> getBusinesses()

getLocations

java.util.List<Location> getLocations()

getPhones

java.util.List<Phone> getPhones()

getEntities

java.util.List<Entity> getEntities()

A convenience method for getting the concatenation of the entity lists.

Returns:

Concatenated list of all entities associated with this entity.

getName

java.lang.String getName()

A standardized method for getting the primary, human readable, formatted String version of this entity.

Returns:

The human formatted string.

isProxy

boolean isProxy()

Returns true if this entity instance is a proxy instance.

Returns:

true if this entity instance is a proxy instance.

See Also:

isLoaded(), load(), EntityProxy

isLoaded

boolean isLoaded()

If the called on a proxy, return true only if the backing entity has been fetched. If called on a concrete entity, then always return true.

Returns:

load status for this entity.

See Also:

isProxy(), load(), EntityProxy

load

void load()
          throws FindException

Causes this instance to load its data by contacting the remote service and requesting information. Once loaded, subsequent calls to this method have no effect.

This method is useful for proxy entities found at the edge of the graph.

Throws:

FindException - If the lookup fails before it is able to generate a Response object.

See Also:

isProxy(), isLoaded(), EntityProxy