xapi.model.api

Class ModelModule

java.lang.Object

xapi.model.api.ModelModule

All Implemented Interfaces:

Serializable

public class ModelModule
extends Object
implements Serializable

This class represents a module of model types; it contains the ModelManifests for all types within this module. In practice, this is used for servers to be able keep in sync with multiple clients; by having the client transmit the strong hash of the ModelModule, the server can load the correct serialization policy to be able to understand any number of clients.

Whenever the server loads the ModelModule, it should save a copy into its datastore, so that, if updated, clients who present a previous strong hash can still function correctly. The server will generally be deployed with a module for each client compilation, which it can save while it is still on the classpath; then, should a new version be deployed, the policy on the classpath will be stale, but can be loaded from the datastore.

Using this technique will allow the server to understand version-skewed clients; however, care must be taken that a breaking change across versions will not lead to server errors. Using generic .getAllProperties() methods will help avoid interface-based changes, but there will still be a problem when an incompatible change is made.

To mitigate this, we will (in the future) first create the ability to invalidate serialization policies that are too old; this can be done with an annatation, @BreakingChange, which signals to the serialization policy builder that the given type cannot be safely used before the current version. This annotaiton will accept an optional hash key to state that "all versions at or before the specified key should be invalidated".

Once we are able to safely prevent breaking changes from causing server errors (we can just send back an error message telling the client to update), then we will build a @MigrationStrategy, which will include instructions on how to transform a stale model into an acceptable format. This annotation will point to helper classes that exist which can transform a given model.

Using a migration strategy will easily facilitate simple field renames or removals, but for more complex situations like adding a field that must be populated from external sources, the ModelMigration interface will take an extra context variable (like an HttpSession) to help the server fill in any data that is not within scope.

When it is not possible to migrate a field, then a @BreakingChange should be used to force the client to update.

Author:

James X. Nelson (james@wetheinter.net, @james)

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
ModelModule()

Method Summary

Modifier and Type	Method and Description
ModelModule	addManifest(ModelManifest manifest)
ModelModule	addStrongName(String strongName)
protected String	calculateSerialization(PrimitiveSerializer primitives)
protected String	computeUuid(PrimitiveSerializer primitives)
static ModelModule	deserialize(CharIterator chars, PrimitiveSerializer primitives)
static ModelModule	deserialize(String chars)
boolean	equals(Object obj) This implementation is EXTREMELY INEFFICIENT, and should only be used for unit tests; this object should not be treated as a map key, but if you absolutely must, you should consider using a mapping structure that allows you to provide a more efficient equality check.
ModelManifest	getManifest(String modelType)
String	getModuleName()
String[]	getStrongNames()
String	getUuid()
int	hashCode()
static CharBuffer	serialize(CharBuffer into, ModelModule module, PrimitiveSerializer primitives)
static String	serialize(ModelModule module)
void	setModuleName(String moduleName)
void	setUuid(String uuid)

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ModelModule

public ModelModule()

Method Detail

addManifest

public ModelModule addManifest(ModelManifest manifest)

addStrongName

public ModelModule addStrongName(String strongName)

getManifest

public ModelManifest getManifest(String modelType)

getStrongNames

public String[] getStrongNames()

getUuid

public String getUuid()

Returns:

-> uuid

computeUuid

protected String computeUuid(PrimitiveSerializer primitives)

setUuid

public void setUuid(String uuid)

Parameters:

uuid - -> set uuid

serialize

public static String serialize(ModelModule module)

serialize

public static CharBuffer serialize(CharBuffer into,
                                   ModelModule module,
                                   PrimitiveSerializer primitives)

calculateSerialization

protected String calculateSerialization(PrimitiveSerializer primitives)

deserialize

public static ModelModule deserialize(String chars)

deserialize

public static ModelModule deserialize(CharIterator chars,
                                      PrimitiveSerializer primitives)

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

This implementation is EXTREMELY INEFFICIENT, and should only be used for unit tests; this object should not be treated as a map key, but if you absolutely must, you should consider using a mapping structure that allows you to provide a more efficient equality check.

Overrides:

equals in class Object

getModuleName

public String getModuleName()

Returns:

-> moduleName

setModuleName

public void setModuleName(String moduleName)

Parameters:

moduleName - -> set moduleName