To obtain the {@code PrimaryIndex} for a given entity class, call {@link EntityStore#getPrimaryIndex EntityStore.getPrimaryIndex}, passing the primary key class and the entity class. For example:
EntityStore store = new EntityStore(...); {@code PrimaryIndex} primaryIndex =store.getPrimaryIndex(Long.class, Employee.class); Note that {@code Long.class} is passed as the primary key class, but theprimary key field has the primitive type {@code long}. When a primitive primary key field is used, the corresponding primitive wrapper class is used to access the primary index. For more information on key field types, see {@link PrimaryKey}.
The {@code PrimaryIndex} provides the primary storage and access methodsfor the instances of a particular entity class. Entities are inserted and updated in the {@code PrimaryIndex} by calling a method in the family of{@link #put} methods. The {@link #put} method will insert the entity if noentity with the same primary key already exists. If an entity with the same primary key does exist, it will update the entity and return the existing (old) entity. For example:
Employee oldEntity; oldEntity = primaryIndex.put(new Employee(1, "Jane Smith")); // Inserts an entity assert oldEntity == null; oldEntity = primaryIndex.put(new Employee(2, "Joan Smith")); // Inserts an entity assert oldEntity == null; oldEntity = primaryIndex.put(new Employee(2, "Joan M. Smith")); // Updates an entity assert oldEntity != null;
The {@link #putNoReturn} method can be used to avoid the overhead ofreturning the existing entity, when the existing entity is not important to the application. The return type of {@link #putNoReturn} is void. Forexample:
primaryIndex.putNoReturn(new Employee(1, "Jane Smith")); // Inserts an entity primaryIndex.putNoReturn(new Employee(2, "Joan Smith")); // Inserts an entity primaryIndex.putNoReturn(new Employee(2, "Joan M. Smith")); // Updates an entity
The {@link #putNoOverwrite} method can be used to ensure that an existingentity is not overwritten. {@link #putNoOverwrite} returns true if theentity was inserted, or false if an existing entity exists and no action was taken. For example:
boolean inserted; inserted = primaryIndex.putNoOverwrite(new Employee(1, "Jane Smith")); // Inserts an entity assert inserted; inserted = primaryIndex.putNoOverwrite(new Employee(2, "Joan Smith")); // Inserts an entity assert inserted; inserted = primaryIndex.putNoOverwrite(new Employee(2, "Joan M. Smith")); // No action was taken! assert !inserted;
Primary key values must be unique, in other words, each instance of a given entity class must have a distinct primary key value. Rather than assigning the unique primary key values yourself, a sequence can be used to assign sequential integer values automatically, starting with the value 1 (one). A sequence is defined using the {@link PrimaryKey#sequence}annotation property. For example:
{@literal @Entity}class Employee { {@literal @PrimaryKey(sequence="ID")}long id; String name; Employee(String name) { this.name = name; } private Employee() {} // For bindings } The name of the sequence used above is "ID". Any name can be used. If the same sequence name is used in more than one entity class, the sequence will be shared by those classes, in other words, a single sequence of integers will be used for all instances of those classes. See {@link PrimaryKey#sequence} for more information.
Any method in the family of {@link #put} methods may be used to insertentities where the primary key is assigned from a sequence. When the {@link #put} method returns, the primary key field of the entity object will be setto the assigned key value. For example:
Employee employee; employee = new Employee("Jane Smith"); primaryIndex.putNoReturn(employee); // Inserts an entity assert employee.id == 1; employee = new Employee("Joan Smith"); primaryIndex.putNoReturn(employee); // Inserts an entity assert employee.id == 2; This begs the question: How do you update an existing entity, without assigning a new primary key? The answer is that the {@link #put} methodswill only assign a new key from the sequence if the primary key field is zero or null (for reference types). If an entity with a non-zero and non-null key field is passed to a {@link #put} method, any existing entitywith that primary key value will be updated. For example:
Employee employee; employee = new Employee("Jane Smith"); primaryIndex.putNoReturn(employee); // Inserts an entity assert employee.id == 1; employee = new Employee("Joan Smith"); primaryIndex.putNoReturn(employee); // Inserts an entity assert employee.id == 2; employee.name = "Joan M. Smith"; primaryIndex.putNoReturn(employee); // Updates an existing entity assert employee.id == 2; Since {@code PrimaryIndex} implements the {@link EntityIndex} interface,it shares the common index methods for retrieving and deleting entities, opening cursors and using transactions. See {@link EntityIndex} for moreinformation on these topics.
Note that when using an index, keys and values are stored and retrieved by value not by reference. In other words, if an entity object is stored and then retrieved, or retrieved twice, each object will be a separate instance. For example, in the code below the assertion will always fail.
MyKey key = ...; MyEntity entity1 = new MyEntity(key, ...); index.put(entity1); MyEntity entity2 = index.get(key); assert entity1 == entity2; // always fails!@author Mark Hayes
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |