Skip to content

Latest commit

 

History

History
87 lines (79 loc) · 4.81 KB

design.md

File metadata and controls

87 lines (79 loc) · 4.81 KB

Notes about the design of Prism

Automatic and annotation-driven

Type analyzers should work with as little configuration as possible. This often requires searching for multiple possible solutions to a problem and picking the best one. For example, a List analyzer could implement multiple strategies for instantiating new objects:

  • use a zero-argument constructor and call addAll
  • use a constructor that accepts another list
  • or use a constructor that accepts an array

Compatibility

Type analyzers should have built-in support for as many libraries as possible, using the (as yet unimplemented) NoClassDefFoundError-tolerant class loading functionality of Mirror to only load these classes if they are present. For example, optimized list/set serializers for the primitive collection types found in trove and fastutil.

Useful failures

(this behavior is up in the air, I'm not sure how best to handle it. This is just the idea so far) Serializers should fail at whatever point would be most useful for the user, failing immediately when essential requirements aren't met, but only failing when optional functionality is actually used. For example, A List analyzer should fail immediately if a serializer couldn't be found for its component type, but if it couldn't find a constructor it should only fail when an instance actually needs to be created.

Descriptive errors

Exception messages should be very descriptive and ideally provide a short recommendation for how to fix the error. Serialization logic is often very complicated and daunting for the average user, so if possible they should end with a recommendation for how to fix the error or what to check to investigate the error. For example:

com.teamwizardry.prism.DeserializationException: Error deserializing `com.pack.age.CoolContainer<com.pack.age.CoolObject>`. 
  An exception was thrown deserializing the field `com.pack.age.AbstractContainer<com.pack.age.CoolObject>.contents`.
    at ...
    at ...
Caused by: com.teamwizardry.prism.InstantiationException: Could not create a new instance of `com.pack.age.CoolObject`.
  Final fields (id, size) had to be modified but no suitable constructor was be found. See ObjectAnalyzer for information on final fields.
    at ...
    at ...
Error creating serializer for `com.teamwizardry.wizardry.CoolDataContainer` using `com.teamwizardry.librarianlib.NBTObjectSerializerFactory`
Caused by "property 'data'": Error creating serializer for `java.util.List<com.teamwizardry.wizardry.CoolDataObject>` using `com.teamwizardry.librarianlib.NBTListSerializerFactory`
Caused by "element type": Error creating serializer for `com.teamwizardry.wizardry.CoolDataObject` using `com.teamwizardry.librarianlib.NBTObjectSerializerFactory`
Caused by: dev.thecodewarrior.prism.base.analysis.ObjectAnalysisException: Errors scanning properties of `com.teamwizardry.wizardry.CoolDataObject`
    There are multiple properties named "value":
        - (field) CoolDataObject.value
        - (method) CoolDataObject.getValue
    There are multiple setters named "size":
        - (method) CoolDataObject.setDataSize
        - (method) CoolDataParent.setValueSize

Error creating serializer for `com.teamwizardry.wizardry.CoolDataObject` (com.teamwizardry.librarianlib.NBTObjectSerializer)
Used by "element type" in `java.util.List<com.teamwizardry.wizardry.CoolDataObject>` (com.teamwizardry.librarianlib.NBTListSerializer)
Used by "property 'data'" in `com.teamwizardry.wizardry.CoolDataContainer` (com.teamwizardry.librarianlib.NBTObjectSerializer)
Errors:
    There are multiple properties named "value":
        - (field) CoolDataObject.value
        - (method) CoolDataObject.getValue
    There are multiple setters named "size":
        - (method) CoolDataObject.setDataSize
        - (method) CoolDataParent.setValueSize

Error creating serializer for `com.teamwizardry.wizardry.CoolDataObject` (com.teamwizardry.librarianlib.NBTObjectSerializer)
Used by "element type" in `java.util.List<com.teamwizardry.wizardry.CoolDataObject>` (com.teamwizardry.librarianlib.NBTListSerializer)
Used by "property 'data'" in `com.teamwizardry.wizardry.CoolDataContainer` (com.teamwizardry.librarianlib.NBTObjectSerializer)
java.lang.RuntimeException: Some other exception here
	at com.teamwizardry.librarianlib.NBTObjectSerializer.create(NBTObjectSerializer.kt:143)
    at ...
Caused by: ...

PrismContextException(
    type = NBTObjectSerializerFactory.class,
    cause = PrismNamedException(
        name = "property 'data'",
        cause = PrismContextException(
            type = NBTListSerializerFactory.class,
            cause = ...
        )
    )
)