Introduction to Beans

What are beans?

Beans is a concept brought over from JavaBeans.
These classes encapsulate many objects and their methods into a single object.
Beans are stored in temporary storage while they are being updated.

Where are beans stored?

A bean store is used to hold temporary session beans.
When a bean is created or loaded from the platform it will be assigned a temporary beanId property and stored in the bean store.
The beanId is used to maintain a reference to the bean through the lifecycle of the bean, allowing it to be updated, until the it is either cleaned, reloaded, stored or removed from the platform

The 3 Beans of our API

Facade Beans

Facade beans are the gateway to access the entity and search beans.
Facade beans hold the logically grouped methods for that class (i.e. lists).
All requests will be made to the Facade bean, this will perform an operation on the entity/search bean, and return a response. Whether this is a response such as "success" or a representation of the entity bean currently in the bean store.
Facade beans have a set of default methods, as well as unique methods to that class.

Default Methods Available to FACADE beans

Below is a list of default methods available to all Facade beans. To understand how to use these please consult the sections: Request & Response / Anatomy of a Session and the PAINT Reference manual.

Process	Description	Method Parameters	Response
clean	Cancels the current bean (referenced by the beanId) and removes it from the temporary bean store.	"beanID" Id of the bean within the bean store
create	Creates a new blank instance of the entity bean associated with the facade (i.e. list entity) and adds this to the bean store. This can be referenced in the bean store via the returned beanID in the entity bean array.	Entity bean array with all the variables associated with that bean. The beanID for referencing this in the bean store is in this array.
load	Loads an entity bean with a specific id into the bean store the type of entity loaded is the same as the facade. Data is populated in this entity. This can be referenced in the bean store via the returned beanID in the entity bean array.	"entityId" (i.e. listId) Id of the entity within the system itself, can be found through performing a search and examining the returned search bean array.	Loaded Entity bean array with all the variables associated with that bean. The beanID for referencing this in the bean store is in this array.
reload	Reloads the entity bean with in the bean store with the version of the entity in the system therefore scrapping the current bean and any update processes that have taken place upto this point.	"beanID" Id of the bean within the bean store	Reloaded Entity bean array with all the variables associated with that bean. The beanID for referencing this in the bean store is in this array.
remove	Removes the entity bean from the bean store and from the system	"beanID" Id of the bean within the bean store
search	Instantiates the search bean associated with the facade, uses the search parameters to return a list of Ids	"searchParameters" An array of search parameters i.e. "listName"=>"Master_List"	Search bean array returned, contains a list of IDs that can be used to load the entities through the facade associated with this.
store	Validates the properties being passed to the bean entity in the bean store, update the bean, and write this back to the platform and removes the bean from the bean store.	"beanID" Id of the bean within the bean store An array of update properties can also be passed to the bean entity through this (by passing the explicit requirement to perform an update)
update	Validates the properties being passed to the bean entity in the bean store, updates the bean in the store. Does not write changes back to the platform.	"beanID" Id of the bean within the bean store An array of update properties

Entity Beans

Entity beans model a single object as a logical entity, for instance a list ("bus_entity_campaign_list"), with the properties being what define that object within the platform.
Entities are accessed via the aforementioned facades, and returned as the response from a "create" or "load"/"reload" method being called on the facade.
Entity beans exist in the bean store after a "create" or "load/reload" where subsequent updates must reference the returned beanId.
In the bean store it can be manipulated as required before being written back to the platform through either a "store" or "remove" facade method.

Search Beans

Search beans encapsulate the ability to search for an entity and return a list of entity ids.
The returned ids can be used as the parameter for the facade load method.
These search beans are partnered to an entity bean and define parameters with which to search the entities for (i.e. listName). The facade validates the parameters before they are passed to this bean.

Now you've got that principle, let's check out a request and response.