All,
I've made some improvements to the docs at [1], to describe best
practices. Any review / feedback extremely welcome.
Aled
[1] https://github.com/apache/incubator-brooklyn/pull/548
On 02/03/2015 15:43, Aled Sage wrote:
Hi all,
We could do with better guidelines for folk writing entities, so that
it produces "good" persisted state.
By "good", I mean that it will persist and rebind successfully, and
that persisted state will not be overly affected by code changes in
future versions of the relevant entities.
I suggest we add to the section "Writing Persistable Code" in [1], and
that we move this to somewhere more prominent.
---
I wanted to get the community's input on the overall approach, and any
thoughts on the guidelines.
We can switch to PR reviews/comments when it gets into the low-level
details.
_*Current implementation*_
We use xstream to persist/deserialize the Java objects as XML. For an
entity, we persist its attributes and config. We also persist the
policies, enrichers and feeds associated with the entity. We also
persist locations + catalog.
The XML serialized form includes the class name and also the field
names as the XML tags.
We may switch to json for the persistence format. This would give two
benefits:
* Better persistence to things like MongoDB and CouchBase.
* Move towards aligning with our YAML format (used for blueprint
definition), for improved consistency; eventually persisted state
could be deployed to a new Brooklyn!
_*Additional guidelines*_
1. Never use anonymous inner classes.
reason: the MyOuterClass$1 auto-generated name is really brittle,
for if the code is changed in the future.
2. Never use non-static inner classes.
reason: the outer class needs to be serialized as well.
3. Always use sensible field names (and use `transient` whenever you
don't want it persisted).
reason: the field name will be part of the persisted state.
4. Consider using Value Objects for persisted values.
reason: can give clearer separation of responsibilities, and clearer
control of what fields are being persisted (making backwards
compatibility simpler).
5. Consider writing transformers to handle backwards-incompatible code
changes.
reason: Brooklyn supports applying transformations to the persisted
state, which can be done as part of an upgrade process.
_*Additional features?
*_There are a few additional features we could consider supporting:
1. Enforcement of guidelines
e.g. have a CLI option for `brooklyn check-state --strict`. This
would ensure guidelines are followed and that rebind will be possible.
2. Improved error reporting, including in web-console, when there are
rebind problems.
3. Support toJson() / fromJson() on objects being serialized, so that
folk can control their own custom serialization.
4. Support JavaBeans styles (i.e. persisting based on the getter method
name, rather than the field names).
For (3) and (4) I'm hesitant for us to support more stuff (more ways
of doing things) unless it's going to genuinely be of major benefit to
users.
Aled
[1]
https://brooklyn.incubator.apache.org/v/latest/ops/persistence/index.html
