Identifying Objects
Objects (Languages, Abilities, etc.) must be referred to by a complete identification of the object. Often, we refer to this simply as a "KEY", but strictly that is not sufficient. It also requires knowledge of the what type of object you are looking for, which is more complicated than Java Class.
ClassIdentity
We have a concept in PCGen called a ClassIdentity. This is a slightly more specific identity than a Java Class. While some objects have a ClassIdentity that is directly derived from their Java Class (Languages, for example), others require a CATEGORY. This is true of a number of types of objects:
- Abilites
- Subclasses (the parent Class is effectively the Category)
- CompanionMods (the TYPE of the CompanionMod serves as a Category)
- Dynamic Objects (The Category is hidden from the end user, but used internally to distinguish the different Dynamic Object types)
In order to construct or retrieve an object that is Categorized, the full ClassIdentity is required.
Format
When processing information from a persistent format, we often will run into a format. This could be something like NUMBER (which effectively relates to Number.class objects), or it could be more complex, like LANGUAGE (which refers to PCGen Language objects).
Any ClassIdentity is effectively sufficient to identify a Format (though the two are not strictly the same).
A Format is generally handled by a FormatManager. For the Java-native objects, this is a separate manager provided in pcgen.base.format (many of these are actually in the PCGen-base Library).
For the Formats that are derived in PCGen (like LANGUAGE), the ReferenceManufacturer serves double duty as a FormatManager (since it already knows how to do that conversion to/from the persistent format). This is why we are often looking up a ReferenceManufacturer by the ClassIdentity.
Derived Formats
There are a number of derived formats where we will need to decide if these stay derived or become explicit. This includes things like DOMAINSPELLLIST and CLASSSPELLLIST, derived for Domain and PCClass objects respectively. For now they are built in to the code and created after data load is complete. (I don't consider this a top priority to change right now)
Persistence
In general, a ClassIdentity persists in the following form: CLASS CLASS=CATEGORY
- For those items where a CATEGORY doesn't exist, it persists with an upper case version of the short name of the class. So a ClassIdentity derived from Language.class persists as LANGUAGE.
- For those items where a CATEGORY does exist, except Dynamic objects, it persists with an upper case version of the short name of the class, followed by an equals sign, followed by the key of the Category, e.g.: ABILITY=FEAT.
- The convention on capitalization of the Category Key is inconsistent, but in general I believe they are lower case.
- For Dynamic objects, which technically possess a DynamicCategory in order to distinguish the object type internally, the format persists with an upper case version of the key of the Category (which is how the object was defined as a Dynamic). So a Dynamic type of "Movement" would persist as a Format called "MOVEMENT".
- This is part of "planning ahead". Since I expect Dynamic to be able to take over many of the simple existing object types (e.g. LANGUAGE) it makes no sense to have a ton of "DYNAMIC=x" items running all over the data. This does provide a tiny constraint (you can't have a DYNAMIC called NUMBER [ever] or one called SKILL today), but it also eases the transition. Consider an example: If Language converts to a Dynamic, the code would delete the Language.class object, and the only data change would be to add a DYNAMICSCOPE:Language definition to the data control file.
