Making Models Available for Import
RAPID-ML can import reusable data models, API models, or definition libraries using any of the following forms:
- An HTTP or HTTPS URL
- A FILE URL
- A relative or absolute path
Using this basic import mechanism, there are different strategies to make files available for import.
Version Control System with HTTP Access
A version control system that can automatically publish files to HTTP or HTTPS URLs is a convenient way to make RAPID-ML files available for import. GitHub is a good example.
Please note the following caveats:
- The URLs should be accessible in your environment without a user login. If you're using a private repository that requires an interactive user login, there may be extra steps required to make the imports function correctly. This may not be practical, and it may cause imports to fail when run from the command line or automated build, outside of the Eclipse environment.
- Use URLs that resolve to the raw file format. Platforms like GitHub provide different URLs for each file. The pages shown on the website, like this one, are meant for display in a browser. Clicking the 'Raw' view option loads this URL, which provides the file in its plain, machine-readable form. You need to use URLs that provide the raw content.
HTTP Filesystem or Document Repository
If your version control system doesn't automatically create suitable HTTP URLs, or if you want to use a publishing process with its own controls, separate from the VCS, you can publish files to any HTTP-accessible filesystem (e.g. Amazon S3), document repository (e.g. Microsoft SharePoint), or website.
You can also bundle reusable RAPID-ML files into shared projects, typically created with the New RepreZen Project wizard. Users who want to import these components will typically use relative paths.
This is a more specialized setup that has significant consequences:
- This setup allows developers to collaborate more closely on shared models. Developers can branch, commit, and open pull requests against the shared project; and they can do this in their normal development workflow, without switching to a separate environment. So this setup can work well for for small, collaborative teams, working with shared models that are still evolving quickly.
- RAPID-ML imports will only work if developers have imported the shared project alongside their working projects. The presence of the shared project is a dependency that must be met in the development environment, along with any command line or CI/CD automated build environments that need to generate code from RAPID-ML files.
- The project structure in your Eclipse workspace should mirror the structure in the filesystem, so that relative paths can be traversed the same way, whether inside or outside of the Eclipse workspace.
File Hierarchy for the Shared Models
We recommend that you structure the file system using a GPR directory tree, where:
- G = Group. A group is a container for related projects. Including the group is optional, as it is just a virtual container for a set of related projects.
- P = Project. An individual unit of shared content
- R = Release. We recommend using semantic versioning (major.minor.patch).
- G = RepreZen;
- P = Experiments;
- R = 1.1.256.
This would give you a directory path in which you would find various files. You can also choose to split the content into API and data subdirectories.
Symlinks for Major/Minor/Patch Releases
We recommend using a set of symbolic links instead of just a flat list of releases.
- v1.1.256 is a physical directory containing patch-level release;
- v1.1 is a symlink to the latest 1.1.xxx release;
- v1 is a symlink to the latest 1.x.xxx release.
With this structure, each import of a shared resource can bind to the major, minor or patch level, depending on the requirements in that context.
- Binding to an individual patch-level release gives the consumer the highest level of control and stability, but requires a manual change to update to a new release.
- Binding to a major release allows seamless updates to new releases, but may expose the consumer to unexpected changes.
- Binding to a minor release provides a mid-point of stability with a degree of convenience from automatic updates.