In a normal cmdrw file, World Auxiliary is used to store miscellaneous custom data and it will get streamed along with drawing.
In Collaboration, the World Auxiliary is not shared between users.
This article suggests the few places you can use to store any miscellaneous data in specially made Collaboration Project Auxiliaries.
Collaboration Project Auxiliaries
There are 3 types of Auxiliaries implemented in Collaboration Projects, these are Section, Paper Group, and Scenario Auxiliaries.
Each of these Auxiliaries each have a get
and put
function, requiring an id
and key
to retrieve the specific Auxiliary data.
That's because these Auxiliaries are essentially a map(retrieved through id
) containing maps (accessed using key
).
When a user opens a Section/Paper Group/Scenario, it loads the Auxiliary data from the server to the user's computer.
Then when a user closes a Section/Paper Group/Scenario, the Auxiliary data is pushed to the server and deleted from the user's computer.
If a user has an old Section/Paper Group/Scenario opened on another computer, whilst a change has been pushed to the server, the old Section/Paper Group/Scenario will automatically fetch the latest change as soon as possible.
Section & Paper Group Auxiliary
Both Section and Paper Group Auxiliaries belong within the _auxiliaryData
field in the CollCollectionG3
class.
If it is a Section Auxiliary, the key to the map is identified with "sectionAux" + symbol.
If it is a Paper Group Auxiliary, the key is identified with "paperGroupAux" + symbol.
The interfaces to use these Auxiliaries are:
- cm/core/collabG3/collSectionFileType.cm
/** * Get section auxiliary data. */ public Object getSectionAuxiliaryData(CollCollectionG3 this, symbol id, str key) { str->Object auxMap = getSectionAuxMap(id); return auxMap.?get(key); } /** * Put section auxiliary data. */ public void putSectionAuxiliaryData(CollCollectionG3 this, symbol id, str key, Object value) { str->Object auxMap = getSectionAuxMap(id, create=true); auxMap.put(key, value); }
- cm/core/collabG3/collPaperFileType.cm
/** * Get paperGroup auxiliary data. */ public Object getPaperGroupAuxiliaryData(CollCollectionG3 this, symbol id, str key) { str->Object auxMap = getPaperGroupAuxMap(id); return auxMap.?get(key); } /** * Put paperGroup auxiliary data. */ public void putPaperGroupAuxiliaryData(CollCollectionG3 this, symbol id, str key, Object value) { str->Object auxMap = getPaperGroupAuxMap(id, create=true); auxMap.put(key, value); }
Scenario Group Auxiliary
Scenario Auxiliaries function a little different from Sections and Paper Groups, where it stores the data within a collection of CollScenarios.
The interfaces to use these Auxiliaries are:
/** * Get scenario auxiliary data. */ public Object getScenarioAuxiliaryData(CollCollectionG3 this, symbol id, str key) { str->Object auxMap = getScenarioAuxMap(id); return auxMap.?get(key); }
/** * Put scenario auxiliary data. */ public void putScenarioAuxiliaryData(CollCollectionG3 this, symbol id, str key, Object value) { str->Object auxMap = getScenarioAuxMap(id, create=true); auxMap.put(key, value); }
Panel Types in CollabPro
Panel Types have some serious challenges in Collaboration as they rely on the World auxiliary data. This might not seem obvious since it's working locally on a user's computer but does not work when someone else loads the Project.
Redirecting the data to Scenarios is the recommended method to migrate Panel Types.
You can find it from the getSnapperFate()
in cm.abstract.
package cm.abstract;
/** * Get from World */ public SnapperFate getSnapperFate(World world, str key) { if (!world) return null; SnapperBaptistAdmin a = world.getAuxillary(auxBaptistKey).SnapperBaptistAdmin; if (!a) { a = SnapperBaptistAdmin(); world.putAuxillary(auxBaptistKey, a); } SnapperFate b = a.get(key); if (!b) { b = SnapperFate(); a.fates.put(key, b); } return b; }
To something like this where your own SnapperNameAdmin
is implemented:
/** * Get from World */ public SnapperFate getSnapperFate(World world, str key) { if (!world) return null; SnapperNameAdmin a; if (CollScenario scenario = collGetScenarioG3(world.mainSpace)) { a = scenario.auxiliaryData(create=true).get(auxNameKey).SnapperNameAdmin; } else { a = world.getAuxillary(auxNameKey).SnapperNameAdmin; } if (!a) { a = SnapperNameAdmin(); if (CollScenario scenario = collGetScenarioG3(world.mainSpace)) { scenario.auxiliaryData(create=true).put(auxNameKey, a); } else { world.putAuxillary(auxNameKey, a); } } SnapperFate b = a.get(key); if (!b) { b = SnapperFate(); a.fates.put(key, b); } return b; }
Custom Files
Collaboration allows registration of custom file types. CollFileType
or CollDataFileType
can be overridden to choose what it does during save and load.
This article will choose CollDataFileType
to extend from as an example, it comes with rudimentary handling of custom data types.
They both can be found in cm.core.collabG3 :
/** * Coll file type. */ public class CollFileType : abstract, unstreamable, uncopyable {
...
}
/** * Collaboration data file type. * * Abstract Collaboration file type for storing generic data used by extensions. * Extend this class and modify it to save and load the data that you're interested in. */ public class CollDataFileType extends CollFileType : abstract { ...
}
The basic file types (i.e. Section, Paper Group, Scenario) are child classes of
CollFileType
.
How to Implement?
It is not enough to just create a class extended from the suggested classes. The first step is to register the custom file type created from your Extension's init method.
/** * Collab Example Extension. */ package class CollabExampleExtension extends UltraLazyExtension { /** * Initialize. */ public void initialize(ExtensionEnv env) { super(env); initExampleCollab();
... }
... } /** * Extension init */ package void initExampleCollab() { registerCollExampleDataFileType();
... }
registerCollTestDataFileType()
is recommended to be in the custom class as such:
/** * Coll example data file type. */ private const str cCollExampleDataFileType = "cmexampledatafile"; /** * Coll example data file type. */ public class CollExampleDataFileType extends CollDataFileType { /** * Constructor. */ public constructor() { super(cCollExampleDataFileType, "CustomData"); } } /** * Coll example data file type. */ public CollFileType collExampleDataFileType() { return registeredCollFileType(cCollExampleDataFileType); } /** * Register coll example data file type. */ package void registerCollExampleDataFileType() { if (!collExampleDataFileType()) { register(CollExampleDataFileType()); } } /** * Unregister coll example data file type. */ package void unregisterCollExampleDataFileType() { if (collExampleDataFileType()) { unregisterCollFileType(cCollExamplestDataFileType); } }
CollDataTypeFile has these methods to extend from:
processLoadData(CollLoadEnvG3 env, CollFileG3 file, str->Object data)
The
data
argument can be thought of as the inherent map of data stored from loading the file coming from the server.
The version of your custom file type is stored here using theversionKey()
method below as access. As such, this is the perfect place to process older version files to the new versions.
You can access the loading file's version byfile.version
.collectSaveData(CollSaveEnvG3 env, CollFileG3 file)
This method returns the inherent map of data intended to be pushed uploaded into the server.
As such, this is the perfect place in insert data regarding any work done to this custom data.version()
Returns the latest version number of this custom data.
Change the version number here whenever there is a need for migration code in this custom file type.versionKey()
The key to access the version data of the incoming file from the server.
Then here are some other important things to keep an eye on:
alwaysLoad()
When the Project a user is working on receives an update from the server, this parameter decides if files of this type will automatically receive the latest update immediately.
- For singleton files (i.e. no more than 1 should exist for this type), it should be noted to use a fixed
id
instead of a random generated one.
Comments
0 comments
Please sign in to leave a comment.