Hi Mark, (by the way, this is probably a question better suited to isis-dev, so I've cc'ed this reply there).
There's not an awful lot of documentation, but in any case I'm reworking some of the runtime APIs as I implement the new JDO/DataNucleus object store (simplifying them since we no longer have the proxy/remoting support). So any docs that I point you to is likely to be somewhat out-of-date. What I do intend to do (and we've intended to for a while) is to create a set of "contract tests" for objectstores, so that new implementations can be more easily verified. We have done some work towards this already; the tck-dom project now holds the various DOM classes used by object stores (and some of the viewers), and there is also the rather useful IsisSystemWithFixtures class that acts as a JUnit @TestRule. This allows us to bootstrap the entire runtime, with a specific object store. Can I ask, though, what object store were you looking to implement? If your requirements overlap with the work I'm doing on JDO, then maybe you could contribute instead by helping test this new object store? ~~~ But, whatever, to answer your question, the APIs as they currently stand in trunk are as follows: * PersistenceMechanismInstaller is the factory for creating a persistence mechanism. The implementation to use is looked up by InstallerLookupDefault (which reads isis.properties etc). * The impl creates relevant subcomponents; these make up a PersistenceSession. A PersistenceSession is similar to a Hibernate session/JPA PersistenceContext. * The PersistenceSession implements several interfaces (this stuff hot off the press!). The most significant is Persistor, the main "client-side" API, and provides an interface to allow a viewer to find instances, load objects, resolve objects, create new instances and persist them, update objects, and delete them. * The Persistor interface also exposes the AdapterManager. This subcomponent also provides mechanisms for obtaining ObjectAdapters. An ObjectAdapter wraps the pojo + the Oid which keeps track of its identity over time + resolve state + version. The AdapterManager maintains pojo <-> adapter and oid <-> adapter maps (ie acts like a short-term cache). Typically adapters will already be in memory; if not then the adapter will be loaded. * the other interfaces exposed by PersistenceSession are mostly internal APIs. Still, it's worth describing them if only to identify some of the use cases that we support: - AdapterRecreator is used by viewers that have an Oid (eg from some URL) and want to recreate an object adapter for an already-persisted object. - ToPersistObjectSet is primarily used by the persist algorithm(s), which determines how persistence-by-reachability is performed; - EnlistedObjectDirtying is used by the IsisTransactionManager to ensure that any ObjectAdapters that were marked as dirty have SaveCommands (to update them) performed. This is only needed for object stores that don't provide their own dirty tracking mechanism (the JDO object store doesn't require this functinality) - RecreatedPojoRemapper is used for internal components that have acquired a pojo and need to remap it. Usually this is in the guts of the ObjectStore implementations, but it is also used by Isis' Memento API and is available for any viewers that (by whatever means) have serialized the state of a pojo and are now deserializing it). - AdapterLifecycleTransitioner is used for ObjectStore implementations to transition an adapter from transient to persistent, or to remove it if deleted. I only named some of these on Friday just gone, so beware I might find better names / readjust the responsibilities slightly. For example, there is quite a lot of similarity between AdapterRecreator and the AdapterManager API, so I might end up combining them. ~~~ But in terms of the actual work needed to implement an object store, it comes down to: - a fairly trivial implementation of PersistenceMechanismInstaller - an implementation of ObjectStore, created in a factory method of your above installer impl - an implementation of IdentifierGenerator, which is used to create the values of ids that are held by the Oid - which implementation of ObjectFactory to use. Some objectstores use the cglib or javassist versions in order to get lazy loading (the JDO object store does not because JDO does lazy loading automatically) - an implementation of PojoRecreator. Many object stores use a preexisting default one (though the JDO object store provides its own implementation that allows it to create the pojo and enlist into the JDO persistence context) - there are some other factory method hooks too, though usually they won't need overriding. One area where there is a little untidiness currently is that the ObjectFactory impl often goes hand-in-hand with the ClassSubstitutor impl; the latter can be used to ignore cglib-generated subclasses, for example. Currently this isn't part of the PersistenceMechanismInstaller, but it probably ought to be. Another thing we're thinking of doing is extending the PersistenceMechanism API to also specify additional FacetFactories. Again, in the JDO impl I currently require DataNucleusProgrammingModelFacets to be used in order to cope with the JDO enhancement process. This API could be improved so that, instead, the PersistenceMechanism "contributes" a set of additional facet factories to whatever the current programming model definition is. Lots of information there, hope some of it was of use! Dan On 12 August 2012 19:43, Mark Wood-Patrick <[email protected]> wrote: > Is there any documentation (apart from the code) on the interface to the > object stores and how to add a new kind of object store? > > Mark > > > ----------------------------------------------------------------------------------- > This email message is for the sole use of the intended recipient(s) and > may contain > confidential information. Any unauthorized review, use, disclosure or > distribution > is prohibited. If you are not the intended recipient, please contact the > sender by > reply email and destroy all copies of the original message. > > ----------------------------------------------------------------------------------- >
