Package org.openxava.model

Class MapFacade

java.lang.Object
org.openxava.model.MapFacade
public class MapFacade extends Object
Allows manage model objects in 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.
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).

Transactional behaviour

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.
The data is flushed in each MapFacade call, but not committed.
This behavior can be modified for your application with the next property in xava.properties file: 
 mapFacadeAutoCommit=true
If 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);
                ... 
 }
Author:
Javier Paniza

  • Field Details

  • Constructor Details

    • MapFacade

      public MapFacade()

  • Method Details

    • create

      public static Object create(String modelName, Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
      Creates a new entity from a map with its initial values.

      Parameters:
      modelName - OpenXava model name. Not null
      values - Initial values for create the entity. Not null. By value semantics.
      Returns:
      Created entity, not a map it's the created object (EntityBean, POJO object o the form used in the underlying model). Not null.
      Throws:
      javax.ejb.CreateException - Logic problem on creation.
      ValidationException - Data validation problems.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.

    • commit

      public static void commit() throws SystemException
      Commit in database the changes done using MapFacade.

      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.

      Throws:
      IllegalStateException - If mapFacadeAutoCommit=true or mapFacadeAsEJB=true in xava.properties
      SystemException - System problem. Rollback transaction.

    • createAggregate

      public static Object createAggregate(String modelName, Map containerKey, int counter, Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
      Deprecated.
      Use createAggregate(String modelName, Map containerKey, String collectionName, Map values) instead
      Creates a new aggregate from a map with its initial values.

      Parameters:
      modelName - OpenXava model name. Not null
      containerKey - 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.
      Returns:
      Aggregate created, not a map but the create object (EntityBean, POJO object o the form used in the underlying model). Not null.
      Throws:
      javax.ejb.CreateException - Logic problem on creation.
      ValidationException - Data validation problems.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.

    • createAggregate

      public static Object createAggregate(String modelName, Map containerKey, String collectionName, Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
      Creates a new aggregate from a map with its initial values.

      Parameters:
      modelName - OpenXava model name. Not null
      containerKey - 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.
      Returns:
      Aggregate created, not a map but the create object (EntityBean, POJO object o the form used in the underlying model). Not null.
      Throws:
      javax.ejb.CreateException - Logic problem on creation.
      ValidationException - Data validation problems.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.
      Since:
      5.3

    • createAggregate

      public static Object createAggregate(String modelName, Object container, int counter, Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
      Deprecated.
      Use createAggregate(String modelName, Map containerKey, String collectionName, Map values) instead.
      Creates a new aggregate from a map with its initial values.

      Parameters:
      modelName - OpenXava model name. Not null
      container - 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.
      Returns:
      Aggregate created, not a map but the create object (EntityBean, POJO object o the form used in the underlying model). Not null.
      Throws:
      javax.ejb.CreateException - Logic problem on creation.
      ValidationException - Data validation problems.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.

    • createReturningValues

      public static Map createReturningValues(String modelName, Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
      Creates a new entity from a map with its initials values and return a map with the values of created entity.

      Parameters:
      modelName - OpenXava model name. Not null
      values - Initial values to create entity. Not null. By value semantics.
      Returns:
      A map with the created object values. The properties are the sent ones on create.
      Throws:
      javax.ejb.CreateException - Logic problem on creation.
      ValidationException - Data validation problems.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.

    • createReturningKey

      public static Map createReturningKey(String modelName, Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
      Creates a new entity from a map with its initial values and return a map with the key values of the created entity.

      Parameters:
      modelName - OpenXava model name. Not null
      values - Initial values to create the entity. Not null. By value semantics.
      Returns:
      A map with key value of created object
      Throws:
      javax.ejb.CreateException - Logic problem on creation.
      ValidationException - Data validation problems.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.

    • createNotValidatingCollections

      public static Map createNotValidatingCollections(String modelName, Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
      Creates a new entity from a map with its initial values and return a map with the key values of the created entity.

      This method does not validate collections.

      Parameters:
      modelName - OpenXava model name. Not null
      values - Initial values to create the entity. Not null. By value semantics.
      Returns:
      A map with key value of created object
      Throws:
      javax.ejb.CreateException - Logic problem on creation.
      ValidationException - Data validation problems.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.

    • createAggregateReturningKey

      public static Map createAggregateReturningKey(String modelName, Map containerKey, int counter, Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
      Deprecated.
      Use createAggregateReturningKey(String modelName, Map containerKey, String collectionName, Map values) instead.
      Creates a new aggregate from a map with its initial values and return a map with the key.

      Parameters:
      modelName - OpenXava model name. Not null
      containerKey - 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.
      Returns:
      Key values of created aggregate.
      Throws:
      javax.ejb.CreateException - Logic problem on creation.
      ValidationException - Data validation problems.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.

    • createAggregateReturningKey

      public static Map createAggregateReturningKey(String modelName, Map containerKey, String collectionName, Map values) throws javax.ejb.CreateException, ValidationException, XavaException, SystemException
      Creates a new aggregate from a map with its initial values and return a map with the key.

      Parameters:
      modelName - OpenXava model name. Not null
      containerKey - 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.
      Returns:
      Key values of created aggregate.
      Throws:
      javax.ejb.CreateException - Logic problem on creation.
      ValidationException - Data validation problems.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.
      Since:
      5.3

    • getValues

      public static Map getValues(String modelName, Map keyValues, Map memberNames) throws javax.ejb.FinderException, XavaException, SystemException
      Obtain the specified values from entity/aggregate from a map with primary key values.

      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} } }
      Parameters:
      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.
      Returns:
      Map with entity values. Not null.
      Throws:
      javax.ejb.ObjectNotFoundException - If object with this key does not exist
      javax.ejb.FinderException - Logic problem on find.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.

    • getValuesNotTracking

      public static Map getValuesNotTracking(String modelName, Map keyValues, Map memberNames) throws javax.ejb.FinderException, XavaException, SystemException
      Obtain the specified values from entity/aggregate from a map with primary key values, not tracking the query.

      Most methods of MapFacade track the changes/queries (using AccessTracker), but the ones with "NotTracking" suffix do not.
      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} } }
      Parameters:
      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.
      Returns:
      Map with entity values. Not null.
      Throws:
      javax.ejb.ObjectNotFoundException - If object with this key does not exist
      javax.ejb.FinderException - Logic problem on find.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.
      Since:
      7.6

    • getValuesByAnyProperty

      public static Map getValuesByAnyProperty(String modelName, Map searchingValues, Map memberNames) throws javax.ejb.FinderException, XavaException, SystemException
      Obtain the specified values from entity/aggregate searching it by any property.

      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} } }
      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.

      If you use: 

       { "name", "J" }
      Then it returns the values for the first object of which name starts with 'J'.

      If you use: 

       { "description", "%BIG" }
      Then it returns the values for the first object of which description contains "BIG".
      Parameters:
      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.
      Returns:
      Map with entity values. Not null.
      Throws:
      javax.ejb.ObjectNotFoundException - If object with this key does not exist
      javax.ejb.FinderException - Logic problem on find.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.

    • getValues

      public static Map getValues(String modelName, Object entity, Map memberNames) throws XavaException, SystemException
      Obtain the values of the entity/aggregate from the own entity.

      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} } }
      Parameters:
      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.
      Returns:
      Map with entity values. Not null.
      Throws:
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.

    • getKeyValues

      public static Map getKeyValues(String modelName, Object entity) throws XavaException, SystemException
      Obtains the values of the key of entity/aggregate.

      Parameters:
      modelName - OpenXava model name. Not null.
      entity - Object to obtain key values from it. Not null.
      Returns:
      Map with key values. Not null.
      Throws:
      XavaException - Any problem related to OpenXava.
      SystemException - System problem.

    • findEntity

      public static Object findEntity(String modelName, Map keyValues) throws javax.ejb.ObjectNotFoundException, javax.ejb.FinderException, SystemException
      Obtain the entity/aggregate from a map with key values.

      Parameters:
      modelName - OpenXava model name. Not null
      keyValues - Key values of entity to find. Not null. By value semantics.
      Returns:
      The entity or aggregate. Not null
      Throws:
      javax.ejb.ObjectNotFoundException - If object with this key does not exist
      javax.ejb.FinderException - Logic problem on find.
      SystemException - System problem. Rollback transaction.

    • remove

      public static void remove(String modelName, Map keyValues) throws javax.ejb.RemoveException, SystemException, XavaException, ValidationException
      Remove the entity/aggregate from a map with its key.

      Parameters:
      modelName - OpenXava model name. No puede ser nulo.
      keyValues - Valores con la clave de la entidad a borrar. Nunca nulo. By value semantics.
      Throws:
      javax.ejb.RemoveException - Logic problem on remove.
      ValidationException - Data validation problems.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.

    • setValues

      public static void setValues(String modelName, Map keyValues, Map values) throws javax.ejb.ObjectNotFoundException, javax.ejb.FinderException, ValidationException, XavaException, SystemException
      Set new values to a entity/aggregate that is found from its key values.

      Parameters:
      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.
      Throws:
      javax.ejb.ObjectNotFoundException - If object with this key does not exist
      javax.ejb.FinderException - Logic problem on find.
      ValidationException - Data validation problems.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.

    • setValuesNotTracking

      public static void setValuesNotTracking(String modelName, Map keyValues, Map values) throws javax.ejb.ObjectNotFoundException, javax.ejb.FinderException, ValidationException, XavaException, SystemException
      Set new values to a entity/aggregate that is found from its key values without tracking the changes.

      Most methods of MapFacade track the changes/queries (using AccessTracker), but the ones with "NotTracking" suffix do not.

      Parameters:
      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.
      Throws:
      javax.ejb.ObjectNotFoundException - If object with this key does not exist
      javax.ejb.FinderException - Logic problem on find.
      ValidationException - Data validation problems.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.
      Since:
      5.9

    • validate

      public static Messages validate(String modelName, Map values) throws XavaException, SystemException
      Validates the sent values but does not create or update the object.

      Only validates the sent data, it does not certify that exist all needed data to create a new object.

      Parameters:
      modelName - OpenXava model name, can be an qualified aggregate. Not null.
      values - Values to validate. Not null. By value semantics.
      Returns:
      Message list with validation errors. Not null.
      Throws:
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.

    • validateIncludingMissingRequired

      public static Messages validateIncludingMissingRequired(String modelName, Map values) throws XavaException, SystemException
      Validates the sent values and if required values are included, but does not create or update the object.

      Validates the sent data and certify that exist all needed data to create a new object.

      Parameters:
      modelName - OpenXava model name, can be an qualified aggregate. Not null.
      values - Values to validate. Not null. By value semantics.
      Returns:
      Message list with validation errors. Not null.
      Throws:
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.
      Since:
      6.0

    • validateIncludingMissingRequired

      public static Messages validateIncludingMissingRequired(String modelName, Map values, String containerReference) throws XavaException, SystemException
      Throws:
      XavaException
      SystemException

    • toPrimaryKey

      public static Object toPrimaryKey(String entityName, Map keyValues) throws XavaException
      Convert from a map with primary key values to primary key object.

      Throws:
      XavaException

    • removeCollectionElement

      public static void removeCollectionElement(String modelName, Map keyValues, String collectionName, Map collectionElementKeyValues) throws javax.ejb.ObjectNotFoundException, javax.ejb.FinderException, ValidationException, javax.ejb.RemoveException, XavaException, SystemException
      Removes an elemente from a collection.

      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.

      Parameters:
      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.
      Throws:
      javax.ejb.ObjectNotFoundException - If object with this key does not exist
      javax.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.

    • addCollectionElement

      public static void addCollectionElement(String modelName, Map keyValues, String collectionName, Map collectionElementKeyValues) throws javax.ejb.ObjectNotFoundException, javax.ejb.FinderException, ValidationException, XavaException, SystemException
      Add an element to a collection.

      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.

      Parameters:
      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.
      Throws:
      javax.ejb.ObjectNotFoundException - If object with this key does not exist
      javax.ejb.FinderException - Logic problem on find.
      ValidationException - Data validation problems.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.

    • moveCollectionElementToAnotherCollection

      public static void moveCollectionElementToAnotherCollection(String sourceContainerModelName, Map sourceContainerKeyValues, String sourceCollectionName, String targetContainerModelName, Map targetContainerKeyValues, String targetCollectionName, Map collectionElementKeyValues) throws javax.ejb.ObjectNotFoundException, javax.ejb.FinderException, ValidationException, XavaException, SystemException
      Move an element from a collection to another.

      Parameters:
      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.
      Throws:
      javax.ejb.ObjectNotFoundException - If object with this key does not exist
      javax.ejb.FinderException - Logic problem on find.
      ValidationException - Data validation problems.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.
      Since:
      5.9

    • moveCollectionElement

      public static void moveCollectionElement(String modelName, Map keyValues, String collectionName, int from, int to) throws javax.ejb.ObjectNotFoundException, javax.ejb.FinderException, XavaException, SystemException
      Move an element in a collection.

      The collection must be sortable, in JPA it means to be a List with @OrderColumn.

      Parameters:
      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.
      Throws:
      javax.ejb.ObjectNotFoundException - If object with this key does not exist
      javax.ejb.FinderException - Logic problem on find.
      XavaException - Any problem related to OpenXava. Rollback transaction.
      SystemException - System problem. Rollback transaction.
      Since:
      5.6.1