Brooklyn RebindLocation notes, general mechanism for persistence and revivification

brooklyn-rebinding-notes.txt

Rebindable (Entity)
- REBINDING_STATUS sensor -> empty (not rebinding), REBINDING, COMPLETED, FAILED
- getRebindLocationGenerator() -> returns a generator suitable for rebinding this entity
    (where the generator produces a RebindLocation initially, but might also produce json/xml;
    and allow interrogation about whether all descendents etc are rebindable)

RebindLocation {
    /** takes no action but says whether it can rebind */
    boolean canRebind(Entity);
    /** sets config & sensors on entity, returns the locations where the entity should proceed to start
          (NB subsequent start in these locations should be idempotent, at least in case when rebinding)
          internally this may change the state of RebindLocation, and may acquire locks (e.g. in cases where we have several IPs being given to otherwise equivalent resources) */
    Collection<Location> startRebind(Entity)
    /** client _must_ call if called start;
        releases locks, asserts REBINDING_STATUS=REBINDING then sets COMPLETED  / FAILED;
        (perhaps?) returns true if caller _should_ circulate back through startRebind for the same entity */
    boolean endRebind(Entity, Throwable anyProblemEncountered)
}

Base entities (no children, eg most SoftwareProcessEntities):
- start(collection) assumes a singleton, calls startInLocation(singleton)
- startIn(Rebind) calls to RebindLocation.startRebind(entity) which
        sets REBINDING_STATUS=REBINDING
        restores other config and sensors on the entity
        returns the actual bound locations where it should start
    then (at entity.startIn(Rebind)) calls to startIn(resultingLocations)
    then (in finally block after startIn(resultingLocations))
        if REBINDING_STATUS=REBINDING sets COMPLETED (or null if it hasn't rebinded, but just returned eg a default provisioning location)

Factory-based entities (eg Cluster) and mixed-mode entities (ControlledDynamicWebCluster) :
- start(collection) typically just creates and starts nodes either [a] with collection or [b] one for each item from collection;
- trigger rebind behaviour at this factory-based entity if, in [a] collection is singleton containing RebindLocation, and
        in [b] for any item which is Rebind (this would be useful e.g. for factory, rebinding to one location, but launching fresh in another).
    or (better) require [a]
- rebind behavior #1
    call originalRebindLocation.startRebind(entity), setting resultingLocations
    then [a] for each child, child.start(originalRebindLocation.getLocationsForChild(child) ?: resultingLocations)
        or [b] for each item l in resultingLocations call child.start(l) -- l might or might not be RebindLocation
    (and skipping things like resize)
- rebind behaviour #2
    go through RebindLocation.startRebind(entity), setting resultingLocations
        (might be the singleton set containing same, or set containing new ones ... possibly Rebinds wrapping the initial(non-rebind) location for this entity,
        and containing rebind instructions for the children)
    then children provisioned as normal, but they might get passed set containing a RebindLocation which tells them what to do
        (e.g. logic inside RebindLocation which behaves differently depending which entity it is)   


TODO
* how to tell the entity that we are rebinding (if needed) -- the sensor
* specify RunDir and other Driver properties -- SUGGESTED_RUN_DIR conf property?
* repopulate groups - TBD
* serialize - TBD but am imagining a JSON rep'n such as below

JSON - simple, for SoftwareProcEntity

locations: [
    {   type: rebind,
        originalLocations: [ {
            type: "brooklyn....SshMachineLocation",
            config: { ... }
        } ],
        config: {
            // config values set on entity
            httpPort: "8080+",
        },
        sensors: {
            // last set of config values
            httpPort: "8085",
            "avg.reqs.per.sec" : 123, ...
        }
    }
]

JSON - more advanced, for a ControlledDynamicWebCluster

locations: [
    {   type: rebind,
        originalLocations: [ {
            type: "brooklyn....JcloudsLocation",
            config: { ... }
        } ],
        matches: {
            entityType: "ControlledDWC"           
        }
        config: {
            // config values set on entity
            httpPort: "8080+",
        },
        sensors: {
            // last set of config values
            httpPort: "8085",
            "avg.reqs.per.sec" : 123, ...
        }
        children: [
            { type: rebind,
                /* as software process entity before, with additions below */
                matches: {
                    entityType: "NgnixController"
                }
            },
            { type: rebind,
                /* as software process entity before, with additions below */
                matches: {
                    entityType: "JBoss7Server",
                    /** mode to say the locations list ^^ is iterated, assigning one per child;
                            when exhausted the locations reverts to the originalLocations of the parent */
                    assignmentMode: ONE_LOCATION_PER_CHILD
                }
            },
        ]
    }
]