Difference between revisions of "FHIR Package Cache"

From HL7Wiki
Jump to navigation Jump to search
Line 12: Line 12:
  
 
- Windows: c:\users\<username>\.fhir\packages
 
- Windows: c:\users\<username>\.fhir\packages
- Linux: /~/.fhir/packages
+
- Unix/Linux: /~/.fhir/packages
  
 
For system services (daemons):
 
For system services (daemons):
  
 
- Windows: c:\ProgramData\.fhir\packages
 
- Windows: c:\ProgramData\.fhir\packages
- Linux: /var/lib/.fhir/packages
+
- Unix/Linux: /var/lib/.fhir/packages
  
 
The package cache root folder contains a folder per package where the folder name is the package name, a dash and the package version.  
 
The package cache root folder contains a folder per package where the folder name is the package name, a dash and the package version.  
Line 23: Line 23:
 
   hl7.fhir.us.core#0.1.1
 
   hl7.fhir.us.core#0.1.1
 
   
 
   
In addition, the package cache root folder contains a file "packages.ini".
+
In addition, the package cache root folder contains a file ".index.json".
  
Note: package name are not allowed to contain the character "#"
+
Note: package names are not allowed to contain the character "#"
  
= packages.ini =
+
= Packages .index.json =
  
The packages.ini file contains the following content:
+
The packages .index.json file contains the following content:
  
[cache]
+
  {
version=2
+
    "cache-version" : "1",
 +
    "urls" : {
 +
      "[package-id]" : "[canonical]"
 +
    }
 +
  }
  
[urls]
 
packageid=canonical
 
  
 
details:
 
details:
* cache: version = 2 - indicates that the contents of the package cache conform to this specification. Applications using the package cache SHALL check this value and shall refuse to use the cache if the value is != 1
+
* cache: version = 1 - indicates that the contents of the package cache conform to this specification. Applications using the package cache SHALL check this value and shall rebuild the cache if the value is != 1
* urls: a list of mappings between package ids and canonical URLs - shared between applications to save a user resolving the same canonical URL repeatedly
+
* urls: a list of mappings between package ids and canonical URLs - shared between applications to save a user resolving the same canonical URL repeatedly - a map of package-id = canonical URL
  
 
= Folder contents =
 
= Folder contents =
  
In each package folder there is one folder called "package", in which all the content of the package is found, including the package manifest. The contents of the folder are the unpacked version of the GZipped tarball and SHALL otherwise conform to the requirements for the [[FHIR NPM Package Spec]]
+
In each package folder the package is unzipped as it is. The contents of the folder are the unpacked version of the GZipped tarball and SHALL otherwise conform to the requirements for the [[FHIR NPM Package Spec]].
 +
 
 +
There is at least one folder called "package", in which all the content of the package is found, including the package manifest. Other folders with other uses may exist if found in the source package.
 +
 
 +
In addition, the folder contains a file ".index.json" - see below.
  
 
= Recursion =
 
= Recursion =
Line 49: Line 55:
 
A package client must resolve package dependencies recursively, but keep the package cache flat. An installed package should itself not contain any dependencies. All packages are installed on the same level.
 
A package client must resolve package dependencies recursively, but keep the package cache flat. An installed package should itself not contain any dependencies. All packages are installed on the same level.
  
Example:
+
= Package .index.json =
  us.core.valuesets#2.0.0
 
  
= Past Versions =
+
This is a file created by the tool that extracts the package. It contains:
  
[cache]
+
{
version=1
+
  "date" : "[date]",
 +
  "canonicals": {
 +
    "http://hl7.org/fhir/StructureDefinition/actualgroup": "StructureDefinition-actualgroup.json",
 +
    ...
 +
  }
 +
}
  
Cache version #1 specified to use "-" as the version separator for package/version in the cache, but "-" is allowed in both package name, and version, so this was not maintainable. Use "#" instead
+
* [date] : the date of extraction in XML format. Sole purpose is to display to the user how long the package has been in the cache
 +
* canonicals: a map from the canonical URL to the literal filename in the package (this makes access faster)

Revision as of 21:08, 5 July 2019

Package Cache

Each system has a global package cache that stores the packages known to that system. This cache is shared between tools for efficiency. Authors of tools that work with FHIR packages are encouraged to follow this specification for the convenience of users.

The package cache keeps the uncompressed content of all installed packages. Different versions of a package are installed side-by-side, and are individually resolvable. A Fhir package client should use the global package cache, but may keep a local cache in a working folder instead. The global package cache makes sure that each packages is installed only once on the computer

Location

The location differs per operating system.

Location of the global package cache:

- Windows: c:\users\<username>\.fhir\packages - Unix/Linux: /~/.fhir/packages

For system services (daemons):

- Windows: c:\ProgramData\.fhir\packages - Unix/Linux: /var/lib/.fhir/packages

The package cache root folder contains a folder per package where the folder name is the package name, a dash and the package version.

 hl7.fhir.us.core#0.1.1

In addition, the package cache root folder contains a file ".index.json".

Note: package names are not allowed to contain the character "#"

Packages .index.json

The packages .index.json file contains the following content:

 {
   "cache-version" : "1",
   "urls" : {
      "[package-id]" : "[canonical]" 
   }
 }


details:

  • cache: version = 1 - indicates that the contents of the package cache conform to this specification. Applications using the package cache SHALL check this value and shall rebuild the cache if the value is != 1
  • urls: a list of mappings between package ids and canonical URLs - shared between applications to save a user resolving the same canonical URL repeatedly - a map of package-id = canonical URL

Folder contents

In each package folder the package is unzipped as it is. The contents of the folder are the unpacked version of the GZipped tarball and SHALL otherwise conform to the requirements for the FHIR NPM Package Spec.

There is at least one folder called "package", in which all the content of the package is found, including the package manifest. Other folders with other uses may exist if found in the source package.

In addition, the folder contains a file ".index.json" - see below.

Recursion

A package client must resolve package dependencies recursively, but keep the package cache flat. An installed package should itself not contain any dependencies. All packages are installed on the same level.

Package .index.json

This is a file created by the tool that extracts the package. It contains:

{

 "date" : "[date]",
 "canonicals": {
   "http://hl7.org/fhir/StructureDefinition/actualgroup": "StructureDefinition-actualgroup.json",
   ...
 }

}

  • [date] : the date of extraction in XML format. Sole purpose is to display to the user how long the package has been in the cache
  • canonicals: a map from the canonical URL to the literal filename in the package (this makes access faster)