Please note that Sincerity is still under development and that this documentation is incomplete.
Specifications
Sincerity Packages
Packages are collections of artifacts. They are defined using special tags in standard JVM resource manifests. Additionally, packages support special install/uninstall hooks for calling arbitrary entry points, allowing for custom behavior. Indeed, a package can include no artifacts, and only implement these hooks.
Packages allow you to work around various limitations in repositories such as iBiblio/Maven, in which the smallest deployable unit is a Jar. The package specification allows you to include as many files as you need in a single Jar, greatly simplifying your deployment scheme.
Note that two different ways are supported for specifying artifacts: they can specified as files, thus referring to actual zipped entries with the Jar file in which the manifest resides, or that can be specified as general resources, in which case they will be general resource URLs to be loaded by the classloader, and thus they can reside anywhere in the classpath.
Also note what "volatile" means in this context: a "volatile" artifact is one that should be installed once and only once. This means that subsequent attempts to install the package, beyond the first, should ignore these artifacts. This is useful for marking configuration files, example files, and other files that the user should be allow to delete without worrying that they would reappear on every change to the dependency structure.
The Manifest
Supported manifest tags:
- Package-Files: a comma separated list of file paths within this Jar.
- Package-Folders: a comma separated list of folder paths within this Jar. Specifies all artifacts under these folders, recursively.
- Package-Resources: a comma separated list of resource paths to be retrieved via the classloader.
- Package-Volatile-Files: all these artifacts will be marked as volatile.
- Package-Volatile-Folders: all artifacts under these paths will be marked as volatile.
- Package-Installer: specifies a class name which has a main() entry point. Simple string arguments can be optionally appended, separated by spaces. The installer will be called when the package is to be installed, after all artifacts have been unpacked. Any thrown exception would cause installation to fail.
- Package-Uninstaller: specifies a class name which has a main() entry point. Simple string arguments can be optionally appended, separated by spaces. The uninstaller will be called when the package is to be uninstalled.
For example, here is a "/META-INF/MANIFEST.MF" file:
Manifest-Version: 1.0 Package-Folders: package
All packaged files would be expected under the "/package/" directory inside the Jar.
Note that manifests can often be automatically created by packaging tools. See the Maven example.
The Sincerity Manual is provided for you under the terms of the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. The complete manual is available for download as a PDF.
