The assignment operations for container-managed relationships have a special semantics that is determined by the referential integrity semantics for the relationship multiplicity.
In the case of a one-to-one relationship, when the Bean Provider uses a set accessor method to assign an object from a cmr-field in one instance to a cmr-field of the SAME relationship type (i.e., as defined by the ejb-relation and ejb-relationship-role deployment descriptor elements) in another instance, the object is effectively MOVED and the value of the source cmr-field is set to null in the same transaction context. If the argument to the set accessor method is NOT of the same type as the cmr-field, the container MUST throw the java.lang.IllegalArgumentException.
In the case of a one-to-many or many-to-many relationship, either the java.util.Collection API or a set accessor method may be used to manipulate the contents of a collection-valued cmr-field. These two approaches are discussed below.
The methods of the java.util.Collection API for the container-managed collections used for collection-valued cmr-fields have the usual semantics, with the following exception: the add and addAll methods applied to container-managed collections in one-to-many relationships have a special semantics that is determined by the referential integrity of one-to-many relationships.
If the argument to the add method is already an element of a collection-valued relationship field of the same relationship type as the target collection (as defined by the ejb-relation and ejb-relationship-role deployment descriptor elements), it is removed from this first relationship and added, in the same transaction context, to the target relationship (i.e., it is effectively moved from one collection of the relationship type to the other). For example, if there is a one-to-many relationship between field "person" and "telephones", adding a "telephone" to a new field "person" will have the effect of removing it from its current field "person".
public abstract class PersonBean implements javax.ejb.EntityBean { ... public void addPhoneNumber(PhoneLocal phone) { Collection phoneNumbers = this.getPhoneNumbers(); phoneNumbers.add(phone); } ... }
The addAll method, when applied to a target collection in a one-to-many relationship, has similar semantics, applied to the members of its collection argument individually.
public abstract class PersonBean implements javax.ejb.EntityBean { ... public void addPhoneNumbers(Collection numbers) { Collection phoneNumbers = this.getPhoneNumbers(); phoneNumbers.addAll(numbers); } // relationship fields public abstract Set getPhoneNumbers( ); public abstract void setPhoneNumbers(Set numbers); ... }
Bean Provider MUST NOT modify the container-managed COLLECTION while the iteration is in progress in any way that causes elements to be added or removed, other than by the java.util.Iterator.remove() method. If elements are added or removed from the underlying container-managed collection used by an iterator other than by the java.util.Iterator.remove() method, the container should throw the java.lang.IllegalStateException on the next operation on the iterator.
Collection nySalesreps = nyOffice.getSalesreps(); Collection sfSalesreps = sfOffice.getSalesreps(); Iterator i = nySalesreps.iterator(); Salesrep salesrep; // a WRONG way to transfer the salesrep while (i.hasNext()) { salesrep = (Salesrep)i.next(); sfSalesreps.add(salesrep); // removes salesrep from nyOffice } // this is a CORRECT and safe way to transfer the salesrep while (i.hasNext()) { salesrep = (Salesrep)i.next(); i.remove(); sfSalesreps.add(salesrep); }
The semantics of a set accessor method, when applied to a collection-valued cmr-field, is also determined by the referential integrity semantics associated with the multiplicity of the relationship. The identity of the collection object referenced by a cmr-field does not change when a set accessor method is executed.
In the case of a one-to-many relationship, if a collection of entity objects is assigned from a cmr-field of in one instance to a cmr-field of the same relationship type in another instance, the objects in the collection are effectively MOVED. The CONTENTS of the collection of the target instance are REPLACED with the contents of the collection of the source instance, but the identity of the collection object containing the instances in the relationship does not change. The source cmr-field references the same collection object as before (i.e., the identity of the collection object is preserved), but the collection is empty.
The Bean Provider can thus use the set(...) method to MOVE objects between the collections referenced by cmr-fields of the same relationship type in different instances. The set accessor method, when applied to a cmr-field in a one-to-many relationship thus has the semantics of the java.util.Collection methods clear, followed by addAll, applied to the TARGET collection; and clear, applied to the SOURCE collection. It is the responsibility of the container to transfer the contents of the collection instances in the same transaction context.
public void changeTelephoneNumber() { Address a = getShippingAddress(); Address b = getBillingAddress(); Collection c = b.getTelephoneNumbers(); a.setTelephoneNumbers(b.getTelephoneNumbers()); if (c.isEmpty()) { // MUST be true ... } }
In the case of a many-to-many relationship, if the value of a cmr-field is assigned to a cmr-field of the same relationship type in another instance, the objects in the collection of the first instance are assigned as the contents of the cmr-field of the second instance. The identities of the collection objects referenced by the cmr-fields do not change. The contents of the collections are shared, but not the collections themselves. The set accessor method, when applied to a cmr-field in a many-to-many relationship thus has the semantics of the java.util.Collection methods clear, followed by addAll, applied to the TARGET collection.
public void shareCustomers(SalesRep rep) { setCustomers(rep.getCustomers()); // the customers are shared among the salesreps }
One-to-one bidirectional relationships
EntityBean_B entityBean_B1 = entityBean_A1.getEntityBean_B(); EntityBean_B entityBean_B2 = entityBean_A2.getEntityBean_B();
entityBean_A1.setEntityBean_B(entityBean_A2.getEntityBean_B()); if entityBean_A1.getEntityBean_B().isIdentical(entityBean_B2) { ... } // true if (entityBean_A2.getEntityBean_B() == null) { ... } // true if (entityBean_B1.getEntityBean_A() == null) { ... } // true
One-to-one unidirectional relationships
EntityBean_B entityBean_B1 = entityBean_A1.getEntityBean_B(); EntityBean_B entityBean_B2 = entityBean_A2.getEntityBean_B();
entityBean_A1.setEntityBean_B(entityBean_A2.getEntityBean_B()); if (entityBean_A2.getEntityBean_B() == null) { ... } // true
One-to-many bidirectional relationships
Collection entityBeans_B1 = entityBean_A1.getEntityBean_B(); Collection entityBeans_B2 = entityBean_A2.getEntityBean_B();
entityBean_A1.setEntityBean_B(entityBean_A2.getEntityBean_B()); if (entityBean_A2.getEntityBean_B().isEmpty()) { ... } // true if (entityBeans_B2.isEmpty()) { ... } // true if (entityBean_B11.getEntityBean_A() == null) { ... } // true if (entityBean_A1.isIdentical(entityBean_B21.getEntityBean_A())) { ... // true }
entityBean_B21.setEntityBean_A(entityBean_B11.getEntityBean_A()); if (entityBean_A1.isIdentical(entityBean_B21.getEntityBean_A())) { ... // true } if (entityBeans_B1.contains(entityBean_B21)) { ... } // true
entityBean_A1.getEntityBean_B().add(entityBean_B21); if (entityBean_A1.isIdentical(entityBean_B21.getEntityBean_A())) { ... // true } if (entityBeans_B1.contains(entityBean_B21)) { ... } // true
entityBean_A1.getEntityBean_B().remove(entityBean_B12); if (entityBean_B12.getEntityBean_A() == null) { ... } // true
One-to-many unidirectional relationships
Collection entityBeans_B1 = entityBean_A1.getEntityBean_B(); Collection entityBeans_B2 = entityBean_A2.getEntityBean_B();
entityBean_A1.setEntityBean_B(entityBean_A2.getEntityBean_B()); if (entityBean_A2.getEntityBean_B().isEmpty()) { ... } // true if (entityBeans_B2.isEmpty()) { ... } // true if (entityBean_A1.getEntityBean_B().contains(entityBean_B21)) { ... // true } if (entityBeans_B1.contains(entityBean_B21)) { ... } // true
entityBean_A1.getEntityBean_B().add(entityBean_B21); if (entityBeans_B1 == entityBean_A1.getEntityBean_B()) { ... // true } if (entityBeans_B1.contains(entityBean_B21)) { ... } // true
entityBean_A1.getEntityBean_B().remove(entityBean_B12); if !(entityBean_A1.getEntityBean_B().contains(entityBean_B12)) { ... // true }
Many-to-one unidirectional relationships
if entityBean_A1.isIdentical(entityBean_B11.getEntityBean_A()) { ... } // true if entityBean_A1.isIdentical(entityBean_B12.getEntityBean_A()) { ... } // true if entityBean_A2.isIdentical(entityBean_B21.getEntityBean_A()) { ... } // true if entityBean_A2.isIdentical(entityBean_B22.getEntityBean_A()) { ... } // true
entityBean_B12.setEntityBean_A(entityBean_B22.getEntityBean_A()); if entityBean_A1.isIdentical(entityBean_B11.getEntityBean_A()) { ... } // true if entityBean_A2.isIdentical(entityBean_B12.getEntityBean_A()) { ... } // true if entityBean_A2.isIdentical(entityBean_B21.getEntityBean_A()) { ... } // true if entityBean_A2.isIdentical(entityBean_B22.getEntityBean_A()) { ... } // true
Many-to-many bidirectional relationships
if entityBean_A11.getEntityBean_B().contains(entityBean_B11) { ... } // true if entityBean_A11.getEntityBean_B().contains(entityBean_B12) { ... } // true if entityBean_A12.getEntityBean_B().contains(entityBean_B11) { ... } // true if entityBean_A12.getEntityBean_B().contains(entityBean_B12) { ... } // true if entityBean_A12.getEntityBean_B().contains(entityBean_B21) { ... } // true
entityBean_A11.setEntityBean_B(entityBean_A22.getEntityBean_B()); if entityBean_A11.getEntityBean_B().contains(entityBean_B21) { ... } // true if entityBean_A11.getEntityBean_B().contains(entityBean_B22) { ... } // true if entityBean_A22.getEntityBean_B().contains(entityBean_B21) { ... } // true if entityBean_A22.getEntityBean_B().contains(entityBean_B22) { ... } // true
entityBean_A11.getEntityBean_B().add(entityBean_B21); if entityBean_A11.getEntityBean_B().contains(entityBean_B11) { ... } // true if entityBean_A11.getEntityBean_B().contains(entityBean_B12) { ... } // true if entityBean_A11.getEntityBean_B().contains(entityBean_B21) { ... } // true
entityBean_A12.getEntityBean_B().remove(entityBean_B12); if entityBean_A12.getEntityBean_B().contains(entityBean_B11) { ... } // true if entityBean_A12.getEntityBean_B().contains(entityBean_B21) { ... } // true if entityBean_B12.getEntityBean_A().contains(entityBean_A11) { ... } // true if entityBean_B12.getEntityBean_A().contains(entityBean_A21) { ... } // true
Many-to-many unidirectional relationships
if entityBean_A11.getEntityBean_B().contains(entityBean_B11) { ... } // true if entityBean_A11.getEntityBean_B().contains(entityBean_B12) { ... } // true if entityBean_A12.getEntityBean_B().contains(entityBean_B11) { ... } // true if entityBean_A12.getEntityBean_B().contains(entityBean_B12) { ... } // true if entityBean_A12.getEntityBean_B().contains(entityBean_B21) { ... } // true
entityBean_A11.setEntityBean_B(entityBean_A22.getEntityBean_B()); if entityBean_A11.getEntityBean_B().contains(entityBean_B21) { ... } // true if entityBean_A11.getEntityBean_B().contains(entityBean_B22) { ... } // true if entityBean_A22.getEntityBean_B().contains(entityBean_B21) { ... } // true if entityBean_A22.getEntityBean_B().contains(entityBean_B22) { ... } // true
entityBean_A11.getEntityBean_B().add(entityBean_B21); if entityBean_A11.getEntityBean_B().contains(entityBean_B11) { ... } // true if entityBean_A11.getEntityBean_B().contains(entityBean_B12) { ... } // true if entityBean_A11.getEntityBean_B().contains(entityBean_B21) { ... } // true
entityBean_A12.getEntityBean_B().remove(entityBean_B12); if entityBean_A12.getEntityBean_B().contains(entityBean_B11) { ... } // true if entityBean_A12.getEntityBean_B().contains(entityBean_B21) { ... } // true