Java Doc for SRecordInstance.java in  » Database-ORM » SimpleORM » simpleorm » core » Java Source Code / Java DocumentationJava Source Code and Java Documentation

RecordInstances are created by either SRecordMeta.findOrCreate findOrCreate or SResultSet.getRecord . The former selects a specific record by primary key, while the latter retrieves a record from a general query result set.

The main methods are get* and set* which get and set field values of the record. SRecordInstance.deleteRecord deletes a row.

No two RecordInstances can have the same primary key field values within the same connection. Attempts to retrieve the same row twice will simple return a pointer to an existing SRecordInstance. There is no relationship between RecordInstances in different connections -- all locking is done by the underlying database.

SRecordsInstances may also be SRecordInstance.detach ed from a connection and then subsequently SRecordInstance.attach ed to another connection. Optimistic locking is used.

### Serializable, but only naively. Should throw exception if one attempts to serialize an attached record, or references to purged records. When deserializing, should match meta data with current SRecordMeta. The following of links to referenced records should be manual and should be part of the serialization process and not the detachment process.

This is purely for the purpose of putting SRecordInstances in the SConnection.transactionCache.

If the underlying scalar key values are null, then this always null because there is no record to retrieve.

This is called just before a record would be flushed.

Currently, the returned value is just this. However, a future version may allow the unattached record to be merged with an existing record, so one should always assume that the record may change identity during attachment.

Attaching the same record twice is OK.

If the record has a generated primary key then the key is generated as part of the attachement processing.

This method may only be used while the object is detached.

The record is only deleted from the database when the transaction is committed or is flushed. Thus a transaction that nulls out references to a parent record and then deletes the parent record will not cause a referential integrity violation because the update order is preserved so that the updates will (normally) be performed before the deletes.

Note that for Optimistic locks only those fields that were retrieved are checked for locks.

Nulls any references to records that have not already been detached so that they will not be serialized. The keys are kept so that the references can be reconstructed later. (This does NOT recursively detach any referenced records -- you have to explicitly detach all the records that you need.)

Set nullRefs to false to break instance indirect circular references, eg. if an Employee e manages someone that manages e. Very rarely needed. It is OK to detach a record twice.

Dangerous, use with care.

See Also:   SRecordInstance.flushAndPurge

This is purely for the purpose of putting SRecordInstances in the SConnection.transactionCache. This is done as tc.put(SRecordInstance, SRecordInstance), ie the instance is used for both the key and the body. This avoids having to create a separate primary key object for each record instance.

It only foreign keys, not referenced SRecordInstances which may be null if the parent record has not been retrieved.

## This should really utilize the new batching techniques if the JDBC driver supports them. This would substantially minimize the nr of round trips to the server.

See Also:   SConnection.flush

This is useful if one wants to do raw JDBC updates on the record, and be guaranteed not to have an inconsistent cache. (Where bulk updates can be used they are several times faster than updates made via the JVM -- see the benchmarks section in the white paper.)

Problems with the update order can generally be avoided by first flushing the entire connection.

See Also:   SRecordMeta.flushAndPurge
See Also:   SConnection.flushAndPurge
See Also:   SConnection.flush

  SRecord getMeta() { return meta; }; 

The actual meta variable is thus not Serialized, but it would not be anyway as it is usually static.

If the underlying scalar key values are null, then this always null because there is no record to retrieve. It is only for a non-null, non-retrieved references that this returns FALSE.

By default, this method just returns null to indicate that no last-ditch effort is made to fetch missing references, so you must override it to do something more useful (i.e. fetch the reference from the database)

Warning: Note that because this record and the fetched reference are obtained in separate transactions, any consistency constraints between the two objects might not hold.
Parameters:
  reference - The reference that is being followed
Parameters:
  keys - Object[] keys for the reference, just as you would pass themto THE REFERENCED record's findOrCreate() SRecordInstance Return the fetched record, or null, if no attempt wasmade. NOTE: currently, this does not cover the awkward case where an attempt ISmade, but the value returned is NULL, anyway.

Note that if you do not want trailing spaces trimmed, then just call getObject().toString() manually. (For CHAR fields, most dbs/jdbc drivers seem to trim, but this is highly inconsistent.)

## Trimming is an issue with CHAR style fields that pad with spaces. Currently we always read from database into the fields without trimming. The idea being to let the SimpleORM user get at the raw query result using getObject, whatever that raw result is.

Most DBs seem to trim for us. But some may not, and some may require the trailing spaces on queries. Certainly trailing spaces in the objects will upset the record cache, and there is some dubious code in SRecordFinder.retrieveRecord() to handle this.

I think that for CHAR fields we need to always trim at database read, and pad where needed. This should also be dispatched to DB handler. I think that Oracle gives grief. (Note that trim means trailing spaces, leading should be left alone.)

I have not done this because it would require testing on many datbases.

A record is not dirty if a record has been flushed to the database but the transaction not committed.

## Should add wasEverDirty method for both record and fields for validation tests.

1. Reduce communication burden when sending detached records from a client back to the server for processing
2. Avoid problems when recursively attaching referenced records that we really did not want. attach() currently does not allow multiple attach'es of same record. Even though this reason may evenutually go away, the first reason will remain.

The copy is cheap because it is only copying pointers. However, if the optimisitic lock fails then an exception will be thrown. Mainly used for long lived transactions.

Throw an SValidationException if not OK. The value is not assigned, and the transaction can continue.

This is called after the value has been converted to its proper type, eg. from a String to a Double. (Which is why it is not a good place to also do conversions.)

This is called for key values as well. This is only for newly created records but is during the findOrCreate -- ie it is called even if the record is never made dirty and thus saved. See ADemo and ValidationTest for examples.

This is called just before a record would be flushed. Only dirty records are validated. If the validation fails then the record is not flushed. (It may also be called directly by the application to validate the record before it is flushed.)

Use this routine when a record may be in a temporarily invalid state, but which must be corrected before flushing. This is common when there is a more complex relationship between different fields that cannot be validated until all the fields have been assigned values.

If an exception is thrown then the condition will need to be corrected or the transaction will need to be rolled back.

See ADemo for an example.