File link

Big picture: A file link is a pointer to another file.

Link format

You can get/set the link property of each file in a string format.

It is an ASCII string in form LINKTYPE ARGS:

LINKTYPE is a valid link type, like package.
ARGS is zero or more link type specific arguments. Its size is limited to 65536 bytes.

Link types

A file's link type defines how Boomla treats the link during file operations.

Available link types and their main properties:

	`package`	`scope`	`volume`	`dynamic`	`path`
Address type	hash	hash	hash	location	location
Transparent	yes	yes	yes	yes	no
Filesystem scope	yes	yes	no	no	no
Mounts volume	yes	yes	yes	yes	no
Mounted volume writable	no	yes	yes	yes	n/a
Docs	docs	docs	docs	docs	docs

Link properties

Address type

The address type of a link is either hash-based or location-based.

A hash-based link mounts another volume by its hash. The mounted volume is part of the filesystem and the link can not break. Modifying a hash-linked volume causes hash change propagation in the linking volume.

A package link is a hash-based link. It hard-attaches the mounted package filesystem to the linking file. The hash of the package filesystem affects the hash of the mounting file.

A location-based link references another file by its path or other means. Such links can either mount a volume or simply be used as pointers. Location-based links may be broken as the referenced file may or may not exist. Changing the linked file will not cause hash change propagation in the filesystem.

For example, path link is a location-based link that does not mount another volume, it simply points to another file by an internal path. On the other hand, a dynamic link also mounts the referenced volume.

Transparent link

A link is said to be a transparent link if it lets you transparently read and write the linked file's data except the following:

name,
file hash,
subtree size,
fileId,
fileNodeId,
link.

The rest of the file's data is accessed on the LINKED file:

type,
title,
status code,
attributes,
body,
children,
created, createdBy,
modified, modifiedBy,
subtreeModified, subtreeModifiedBy.

For example, a volume link is a transparent link while a path link is not.

Filesystem scope

The filesystem scope is used for dependency resolution.

When you install a package, the mounted package filesystem will contain lots of files with their own file types which are references to other apps and resources within the package subtree. You want those references to be resolved within the package.

For example, if a file within the package references the resource at /resource and the package is installed at /sys/packages/package.com, you want the resource to be loaded from /sys/packages/package.com/resource, not /resource.

The scope link is also a filesystem scope but it is writable thus allowing you to debug packages or to create self-contained sub-trees.

Mounts volume

Links may mount other volumes which may have different properties.

For example, a package link mounts a volume that is read-only so that subtree will behave slightly differently from the mounting file's volume.

It's important that volume boundaries affect file Ids. Moving a file within the same volume will keep its file Id unchanged. Moving a file to another volume will change its file Id. This may have important side-effects: for example automatic HTTP redirects will not work on that file, so visitors will get a 404 error unless you manually redirect the old location to the new one.

Link behavior

No automatic dereferencing

Boomla files have a dedicated link property so there is no need to immediately dereference file links upon access. It's best to think about file links in Boomla as pointers in programming languages. You can explicitly dereference a pointer, you can change where it points to or the pointer may be followed upon accessing its value. But your variable will still contain the original pointer, not the value it points to.

Similarly in Boomla, some link types are followed when accessing the file’s properties, attributes, body or children - but never the link property. Accessing the link property is always accessed on the linking file, which is very important as you could not edit it otherwise.