public class MapFacade
extends java.lang.Object
Map
format. It's used in generic OpenXava action to make CRUD operations, but if it's convenient for you, you can use directly.
A principle a good design is use maps for generic or automatic things, but in all other cases the use of the model objects directly is better, because the compiler do a good work for us, we can use method calls, etc.
We use the EJB exceptions (CreateException, FinderException, RemoveException,
etc) with the typical semantic associated to each. Although the implementation
does not use EJB.
We use RemoteException to indicate a system error. Although the implementation
is local.
Since version 3.0 MapFacade uses runtime exception for system errors,
before (in v2.x) it used RemoteException.
The first parameter of each method is modelName
, this is a
name of a OpenXava component (Customer, Invoice, etc) or a qualified aggregate
(Invoice.InvoiceDetail for example).
MapFacade
has transactional behaviour inside your action or test (since 2.2.5).
That is, you can write the next code inside an action or test:
public void execute() throws Exception { ... MapFacade.create("Customer", customerValue); MapFacade.create("Invoice", invoiceValue); ... }If
Invoice
creation fails, the Customer will not be saved; moreover
if any other exception is thrown by other sentence of the action. Both Customer
and Invoice data will not be saved.mapFacadeAutoCommit=trueIf you mapFacadeAutoCommit=true or mapFacadeAsEJB=true and you execute the above code, if the creation of
Invoice
fails, the Customer
is already saved and committed and it will not be removed.
When autocommit is not used (the default) you can do a commit programatically, using the @{link #commit()} method. In this way:
public void execute() throws Exception { ... MapFacade.create("Customer", customerValue); MapFacade.commit(); MapFacade.create("Invoice", invoiceValue); ... }
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
MODEL_NAME |
Constructor and Description |
---|
MapFacade() |
Modifier and Type | Method and Description |
---|---|
static void |
addCollectionElement(java.lang.String modelName,
java.util.Map keyValues,
java.lang.String collectionName,
java.util.Map collectionElementKeyValues)
Add an element to a collection.
|
static void |
commit()
Commit in database the changes done using MapFacade.
|
static java.lang.Object |
create(java.lang.String modelName,
java.util.Map values)
Creates a new entity from a map with its initial values.
|
static java.lang.Object |
createAggregate(java.lang.String modelName,
java.util.Map containerKey,
int counter,
java.util.Map values)
Deprecated.
Use createAggregate(String modelName, Map containerKey, String collectionName, Map values) instead
|
static java.lang.Object |
createAggregate(java.lang.String modelName,
java.util.Map containerKey,
java.lang.String collectionName,
java.util.Map values)
Creates a new aggregate from a map with its initial values.
|
static java.lang.Object |
createAggregate(java.lang.String modelName,
java.lang.Object container,
int counter,
java.util.Map values)
Deprecated.
Use createAggregate(String modelName, Map containerKey, String collectionName, Map values) instead.
|
static java.util.Map |
createAggregateReturningKey(java.lang.String modelName,
java.util.Map containerKey,
int counter,
java.util.Map values)
Deprecated.
Use createAggregateReturningKey(String modelName, Map containerKey, String collectionName, Map values) instead.
|
static java.util.Map |
createAggregateReturningKey(java.lang.String modelName,
java.util.Map containerKey,
java.lang.String collectionName,
java.util.Map values)
Creates a new aggregate from a map with its initial values
and return a map with the key.
|
static java.util.Map |
createNotValidatingCollections(java.lang.String modelName,
java.util.Map values)
Creates a new entity from a map with its initial values and
return a map with the key values of the created entity.
|
static java.util.Map |
createReturningKey(java.lang.String modelName,
java.util.Map values)
Creates a new entity from a map with its initial values and
return a map with the key values of the created entity.
|
static java.util.Map |
createReturningValues(java.lang.String modelName,
java.util.Map values)
Creates a new entity from a map with its initials values and
return a map with the values of created entity.
|
static java.lang.Object |
findEntity(java.lang.String modelName,
java.util.Map keyValues)
Obtain the entity/aggregate from a map with key values.
|
static java.util.Map |
getKeyValues(java.lang.String modelName,
java.lang.Object entity)
Obtains the values of the key of entity/aggregate.
|
static java.util.Map |
getValues(java.lang.String modelName,
java.util.Map keyValues,
java.util.Map memberNames)
Obtain the specified values from entity/aggregate from a map with
primary key values.
|
static java.util.Map |
getValues(java.lang.String modelName,
java.lang.Object entity,
java.util.Map memberNames)
Obtain the values of the entity/aggregate from the own entity.
|
static java.util.Map |
getValuesByAnyProperty(java.lang.String modelName,
java.util.Map searchingValues,
java.util.Map memberNames)
Obtain the specified values from entity/aggregate searching it by any property.
|
static void |
moveCollectionElement(java.lang.String modelName,
java.util.Map keyValues,
java.lang.String collectionName,
int from,
int to)
Move an element in a collection.
|
static void |
moveCollectionElementToAnotherCollection(java.lang.String sourceContainerModelName,
java.util.Map sourceContainerKeyValues,
java.lang.String sourceCollectionName,
java.lang.String targetContainerModelName,
java.util.Map targetContainerKeyValues,
java.lang.String targetCollectionName,
java.util.Map collectionElementKeyValues)
Move an element from a collection to another.
|
static void |
remove(java.lang.String modelName,
java.util.Map keyValues)
Remove the entity/aggregate from a map with its key.
|
static void |
removeCollectionElement(java.lang.String modelName,
java.util.Map keyValues,
java.lang.String collectionName,
java.util.Map collectionElementKeyValues)
Removes an elemente from a collection.
|
static void |
setValues(java.lang.String modelName,
java.util.Map keyValues,
java.util.Map values)
Set new values to a entity/aggregate that is found from its key values.
|
static void |
setValuesNotTracking(java.lang.String modelName,
java.util.Map keyValues,
java.util.Map values)
Set new values to a entity/aggregate that is found from its key values without tracking the changes.
|
static java.lang.Object |
toPrimaryKey(java.lang.String entityName,
java.util.Map keyValues)
Convert from a map with primary key values to primary key object.
|
static Messages |
validate(java.lang.String modelName,
java.util.Map values)
Validates the sent values but does not create or update the object.
|
static Messages |
validateIncludingMissingRequired(java.lang.String modelName,
java.util.Map values)
Validates the sent values and if required values are included, but does not create or update the object.
|
static Messages |
validateIncludingMissingRequired(java.lang.String modelName,
java.util.Map values,
java.lang.String containerReference) |
public static final java.lang.String MODEL_NAME
public static java.lang.Object create(java.lang.String modelName, java.util.Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
modelName
- OpenXava model name. Not nullvalues
- Initial values for create the entity. Not null. By value semantics.javax.ejb.CreateException
- Logic problem on creation.ValidationException
- Data validation problems.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static void commit() throws SystemException
It's used rarely because OpenXava module controller commits automatically after each action execution. ModuleTestBase also commits automatically. It's cannot be used if MapFacade auto commit mode is on or it's used as EJB.
java.lang.IllegalStateException
- If mapFacadeAutoCommit=true or mapFacadeAsEJB=true in xava.propertiesSystemException
- System problem. Rollback transaction.public static java.lang.Object createAggregate(java.lang.String modelName, java.util.Map containerKey, int counter, java.util.Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
modelName
- OpenXava model name. Not nullcontainerKey
- Key of entity or aggregate that contains this aggregate. By value semantics.counter
- Counter used to generate the aggregate key, indicates the
order number. The aggregate implementation can ignorate it.values
- Initial values for create the aggregate. Not null. By value semantics.javax.ejb.CreateException
- Logic problem on creation.ValidationException
- Data validation problems.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static java.lang.Object createAggregate(java.lang.String modelName, java.util.Map containerKey, java.lang.String collectionName, java.util.Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
modelName
- OpenXava model name. Not nullcontainerKey
- Key of entity or aggregate that contains this aggregate. By value semantics.collectionName
- The name of the collection.values
- Initial values for create the aggregate. Not null. By value semantics.javax.ejb.CreateException
- Logic problem on creation.ValidationException
- Data validation problems.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static java.lang.Object createAggregate(java.lang.String modelName, java.lang.Object container, int counter, java.util.Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
modelName
- OpenXava model name. Not nullcontainer
- Container object (or container key in object format) that contains
the aggregate.counter
- Counter used to generate the aggregate key, indicates the
order number. The aggregate implementation can ignorate it.values
- Initial values for create the aggregate. Not null. By value semantics.javax.ejb.CreateException
- Logic problem on creation.ValidationException
- Data validation problems.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static java.util.Map createReturningValues(java.lang.String modelName, java.util.Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
modelName
- OpenXava model name. Not nullvalues
- Initial values to create entity. Not null. By value semantics.javax.ejb.CreateException
- Logic problem on creation.ValidationException
- Data validation problems.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static java.util.Map createReturningKey(java.lang.String modelName, java.util.Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
modelName
- OpenXava model name. Not nullvalues
- Initial values to create the entity. Not null. By value semantics.javax.ejb.CreateException
- Logic problem on creation.ValidationException
- Data validation problems.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static java.util.Map createNotValidatingCollections(java.lang.String modelName, java.util.Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
This method does not validate collections.
modelName
- OpenXava model name. Not nullvalues
- Initial values to create the entity. Not null. By value semantics.javax.ejb.CreateException
- Logic problem on creation.ValidationException
- Data validation problems.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static java.util.Map createAggregateReturningKey(java.lang.String modelName, java.util.Map containerKey, int counter, java.util.Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
modelName
- OpenXava model name. Not nullcontainerKey
- Key of entity or aggregate that contains this aggregate. By value semantics.counter
- Counter used to generate the aggregate key, indicates the
order number. The aggregate implementation can ignore it.values
- Initial values for create the aggregate. Not null. By value semantics.javax.ejb.CreateException
- Logic problem on creation.ValidationException
- Data validation problems.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static java.util.Map createAggregateReturningKey(java.lang.String modelName, java.util.Map containerKey, java.lang.String collectionName, java.util.Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
modelName
- OpenXava model name. Not nullcontainerKey
- Key of entity or aggregate that contains this aggregate. By value semantics.collectionName
- Name of the collection.values
- Initial values for create the aggregate. Not null. By value semantics.javax.ejb.CreateException
- Logic problem on creation.ValidationException
- Data validation problems.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static java.util.Map getValues(java.lang.String modelName, java.util.Map keyValues, java.util.Map memberNames) throws javax.ejb.FinderException, XavaException, SystemException
The memberNames
parameter is a map to use a treelike structure.
The property names are in key part. If it's a simple property the value
is null, otherwise it has a map with the same structure.
For example, if we have a Customer that references
to a
Seller
,
we can send a map with the next values:
{ "number", null }
{ "name", null }
{ "seller", { {"number", null}, {"name", null} } }
modelName
- OpenXava model name. Not null.keyValues
- Key values of object to find. Not null. By value semantics.memberNames
- Member names to obtain its values. Not null. By value semantics.javax.ejb.ObjectNotFoundException
- If object with this key does not existjavax.ejb.FinderException
- Logic problem on find.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static java.util.Map getValuesByAnyProperty(java.lang.String modelName, java.util.Map searchingValues, java.util.Map memberNames) throws javax.ejb.FinderException, XavaException, SystemException
The
If you use:
If you use:
memberNames parameter is a map to use a treelike structure.
The property names are in key part. If it's a simple property the value
is null, otherwise it has a map with the same structure.
For example, if we have a Customer that references
to a
Seller
,
we can send a map with the next values:
{ "number", null }
{ "name", null }
{ "seller", { {"number", null}, {"name", null} } }
The searchingValues
parameters are the values used to search.
For example, if you can search by name and surname you can
send to searchingValues
a map with the next values:
{ "name", "JUAN" }
{ "surname", "PEREZ" }
In this case it returns the map with the value of the first "JUAN PEREZ" of database.
{ "name", "J" }
Then it returns the values for the first object of which name starts with 'J'.
{ "description", "%BIG" }
Then it returns the values for the first object of which description contains
"BIG".
modelName
- OpenXava model name. Not null.searchingValues
- Values used for search the object. Not null. By value semantics.memberNames
- Member names to obtain its values. Not null. By value semantics.javax.ejb.ObjectNotFoundException
- If object with this key does not existjavax.ejb.FinderException
- Logic problem on find.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static java.util.Map getValues(java.lang.String modelName, java.lang.Object entity, java.util.Map memberNames) throws XavaException, SystemException
The memberNames parameter is a map to use a treelike structure.
The property names are in key part. If it's a simple property the value
is null, otherwise it has a map with the same structure.
For example, if we have a Customer that references
to a
Seller
,
we can send a map with the next values:
{ "number", null }
{ "name", null }
{ "seller", { {"number", null}, {"name", null} } }
modelName
- OpenXava model name. Not null.entity
- Object to obtain values from it. Not null.memberNames
- Member names to obtain its values. Not null. By value semantics.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static java.util.Map getKeyValues(java.lang.String modelName, java.lang.Object entity) throws XavaException, SystemException
modelName
- OpenXava model name. Not null.entity
- Object to obtain key values from it. Not null.XavaException
- Any problem related to OpenXava.SystemException
- System problem.public static java.lang.Object findEntity(java.lang.String modelName, java.util.Map keyValues) throws javax.ejb.ObjectNotFoundException, javax.ejb.FinderException, SystemException
modelName
- OpenXava model name. Not nullkeyValues
- Key values of entity to find. Not null. By value semantics.javax.ejb.ObjectNotFoundException
- If object with this key does not existjavax.ejb.FinderException
- Logic problem on find.SystemException
- System problem. Rollback transaction.public static void remove(java.lang.String modelName, java.util.Map keyValues) throws javax.ejb.RemoveException, SystemException, XavaException, ValidationException
modelName
- OpenXava model name. No puede ser nulo.keyValues
- Valores con la clave de la entidad a borrar. Nunca nulo. By value semantics.javax.ejb.RemoveException
- Logic problem on remove.ValidationException
- Data validation problems.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static void setValues(java.lang.String modelName, java.util.Map keyValues, java.util.Map values) throws javax.ejb.ObjectNotFoundException, javax.ejb.FinderException, ValidationException, XavaException, SystemException
modelName
- OpenXava model name. Not null.keyValues
- Key values of object. Not null. By value semantics.values
- New values to set. Not null. By value semantics.javax.ejb.ObjectNotFoundException
- If object with this key does not existjavax.ejb.FinderException
- Logic problem on find.ValidationException
- Data validation problems.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static void setValuesNotTracking(java.lang.String modelName, java.util.Map keyValues, java.util.Map values) throws javax.ejb.ObjectNotFoundException, javax.ejb.FinderException, ValidationException, XavaException, SystemException
All methods of MapFacade track the changes (using AccessTracker), but this one.
modelName
- OpenXava model name. Not null.keyValues
- Key values of object. Not null. By value semantics.values
- New values to set. Not null. By value semantics.javax.ejb.ObjectNotFoundException
- If object with this key does not existjavax.ejb.FinderException
- Logic problem on find.ValidationException
- Data validation problems.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static Messages validate(java.lang.String modelName, java.util.Map values) throws XavaException, SystemException
Only validates the sent data, it does not certify that exist all needed data
to create a new object.
modelName
- OpenXava model name, can be an qualified aggregate. Not null.values
- Values to validate. Not null. By value semantics.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static Messages validateIncludingMissingRequired(java.lang.String modelName, java.util.Map values) throws XavaException, SystemException
Validates the sent data and certify that exist all needed data to create a new object.
modelName
- OpenXava model name, can be an qualified aggregate. Not null.values
- Values to validate. Not null. By value semantics.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static Messages validateIncludingMissingRequired(java.lang.String modelName, java.util.Map values, java.lang.String containerReference) throws XavaException, SystemException
XavaException
SystemException
public static java.lang.Object toPrimaryKey(java.lang.String entityName, java.util.Map keyValues) throws XavaException
XavaException
public static void removeCollectionElement(java.lang.String modelName, java.util.Map keyValues, java.lang.String collectionName, java.util.Map collectionElementKeyValues) throws javax.ejb.ObjectNotFoundException, javax.ejb.FinderException, ValidationException, javax.ejb.RemoveException, XavaException, SystemException
If it's a aggregate remove the aggregate, and if it's a entity reference
make the left to point to the parent object, hence left the collection.
Does not delete aggregates directly, but with this method, because
thus the needed logic for remove a element from a collection is executed.
modelName
- OpenXava model name. Not null.keyValues
- Key value of the container of the collection. Not null. By value semantics.collectionName
- Collection name of the container collection of element to remove. Not null.collectionElementKeyValues
- Key value of element to remove. Not null. By value semantics.javax.ejb.ObjectNotFoundException
- If object with this key does not existjavax.ejb.FinderException
- Logic problem on find.ValidationException
- Data validation problems.javax.ejb.RemoveException
- Logic problem on remove.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static void addCollectionElement(java.lang.String modelName, java.util.Map keyValues, java.lang.String collectionName, java.util.Map collectionElementKeyValues) throws javax.ejb.ObjectNotFoundException, javax.ejb.FinderException, ValidationException, XavaException, SystemException
It does not create the element, only adds it to the collection, therefore
for aggregate collections it's not useful using this method, it's better to create
the aggregate using createAggregate
methods.
modelName
- OpenXava model name. Not null.keyValues
- Key value of the container of the collection. Not null. By value semantics.collectionName
- Collection name of the container collection of element to add. Not null.collectionElementKeyValues
- Key value of element to add. Not null. By value semantics.javax.ejb.ObjectNotFoundException
- If object with this key does not existjavax.ejb.FinderException
- Logic problem on find.ValidationException
- Data validation problems.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static void moveCollectionElementToAnotherCollection(java.lang.String sourceContainerModelName, java.util.Map sourceContainerKeyValues, java.lang.String sourceCollectionName, java.lang.String targetContainerModelName, java.util.Map targetContainerKeyValues, java.lang.String targetCollectionName, java.util.Map collectionElementKeyValues) throws javax.ejb.ObjectNotFoundException, javax.ejb.FinderException, ValidationException, XavaException, SystemException
sourceContainerModelName
- OpenXava model name of the container of the source collection. Not null.sourceContainerKeyValues
- Key values of the container of the source collection. Not null. By value semantics.sourceCollectionName
- Source collection name. Not null.targetContainerModelName
- OpenXava model name of the container of the target collection. Not null.targetContainerKeyValues
- Key values of the container of the target collection. Not null. By value semantics.targetCollectionName
- Target collection name. Not null.collectionElementKeyValues
- Key value of element to move. Not null. By value semantics.javax.ejb.ObjectNotFoundException
- If object with this key does not existjavax.ejb.FinderException
- Logic problem on find.ValidationException
- Data validation problems.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.public static void moveCollectionElement(java.lang.String modelName, java.util.Map keyValues, java.lang.String collectionName, int from, int to) throws javax.ejb.ObjectNotFoundException, javax.ejb.FinderException, XavaException, SystemException
The collection must be sortable, in JPA it means to be a List with @OrderColumn.
modelName
- OpenXava model name. Not null.keyValues
- Key value of the container of the collection. Not null. By value semantics.collectionName
- Collection name of the container collection of element to move. Not null.from
- Original position of the element in the collection. Zero based.to
- Position in the collection where the element will be moved. Zero based.javax.ejb.ObjectNotFoundException
- If object with this key does not existjavax.ejb.FinderException
- Logic problem on find.XavaException
- Any problem related to OpenXava. Rollback transaction.SystemException
- System problem. Rollback transaction.