- Subscribe to RSS Feed
- Mark as New
- Mark as Read
- Bookmark
- Subscribe
- Printer Friendly Page
- Report Inappropriate Content
Obsolete Pages{{Obsolete}}
The official documentation is at: http://docs.alfresco.com
{{AVMWarning}}
AVM
Table of Contents
- 1 Overview
- 2 How it works
- 2.1 Initial condition
- 2.2 Transparent objects
- 2.3 Prior to modification: symlink-like behavior
- 2.4 After modification: copy behavior
- 2.5 Deletion of a background object
- 2.6 Background subdirectories
- 2.7 Augmenting a transparent directory
- 2.8 Renames and background files
- 2.9 Renames and background directories
- 2.10 Transparent subdirectories
- 2.11 Gotcha: Stale transparent directories
- 2.12 Deleting transparent directories
- 2.13 Additions beneath a transparent directory
- 2.14 Transparent directories with opaque subdirectories
- 2.15 Transparent Files
- 2.16 Gotcha: Stale transparent files
- 3 Related Work
Overview
A transparent directory (or file) in Alfresco acts like a 'sheet of glass' that can be written upon without affecting the object being viewed. You can either look through it and see the object on the other side, or you can write directly upon it, and see your own data instead. Thus, until you make modifications, a transparent directory (or file) is similar to a UNIX-style symbolic link; however, after making modifications, you're manipulating a detached, private copy of the original.
How it works
Initial condition
Imagine that you have a directory named B that contains a file named cow.html:
Traditionally, in order to make the contents of this directory available somewhere else (e.g.: in a directory named A), you'd have two distinct options:
- Make a separate copy
Issues:- Separate changes in A can be made, but later updates in B aren't seen in A; it's just a snapshot
- Prohibitively expensive if B is large
- Separate changes in A can be made, but later updates in B aren't seen in A; it's just a snapshot
- Use a symbolic link
Issues:- Later updates in B are seen in A, but separate changes in A can't be made; it's merely an alias
- Not well-supported on all operating systems
- Circular references are possible
- Later updates in B are seen in A, but separate changes in A can't be made; it's merely an alias
Transparent objects
Alfresco will allow you make directories (and files) act like windows that can written upon without affecting the object being viewed. If A is a transparent directory, we can indicate this by making the folder icon that represents it 'clear looking'. Let's also attach a miniature image of the B folder next to A icon, to indicate that A is layered on top of B.
Because A is a transparent layer on top of B, you can see the contents of B within A. To indicate that cow.html in A is only visible because it is being seen through a transparent 'window', it's shown using a blue-colored font (mnemonic: objects shown in blue are in the background, like blue mountains in the distance).
Definition:
- Background Object
- A directory (or file) that is seen through the clear barrier offered by a transparent directory (e.g.: cow.html).
- Background Object
Prior to modification: symlink-like behavior
As you'd expect, if you were to add a new file to B, such as moo.txt, you'd see it show up in A immediately:
Note that transparent directory A now contains two background objects: cow.html and moo.txt.
So far, A just behaves very much like a UNIX-style symlink to B.
After modification: copy behavior
If we attempt to change the contents of A/moo.txt, Alfresco will instead create a local copy for modification. To illustrate this, transformation, moo.txt now appears in a black font within A:
A/moo.txt and B/moo.txt will have separate version histories from this point forward.
Definition:
- Foreground Object
- An object that is physically contained within the directory in which appears to reside.
- For example, the only foreground object in A is moo.txt
- Foreground Object
Deletion of a background object
In the previous example, cow.html is still a background object in A. If we were to delete it, here's what we'd see:
Notice that deleting cow.html in A has not altered cow.html in B. Nothing you do to a background object can alter what it once allowed you to see.
Background subdirectories
Examine the previous diagram, and then try to picture what would happen if B/zebras.jpg and B/C/platypus.html were added. Now look at the figure below:
Similar to what we've seen in previous examples, adding a file like B/zebras.jpg causes the background file A/zebras.jpg to appear. What's new in this example is that the creation of B/C causes a background subdirectory to appear: A/C. Here again, when we don't directly modify the transparent directory A, it behaves very much like a symink to B.
Augmenting a transparent directory
Unlike a symlink, transparent directories can contain additional files (and directories) that the object they're viewing does not contain. For example, if duck.html were added to A from the previous example, we'd get this:
Because duck.html is a foreground object in A, it appears in a black font.
Renames and background files
In the previous example, suppose the foreground file B/C/platypus.html is renamed to B/C/egg.html. Notice what happens to the background file A/C/platypus.html below:
Because A is like a 'window' on top of B, A/C/platypus.html becomes A/C/egg.html automatically.
Renames and background directories
Let's start a fresh example. Suppose that directory B contains the files cow.html, moo.txt, and C/egg.html. If A is a transparent directory that is layered on top of B, we'd see something like this:
Notice that within A: cow.html, moo.txt and egg.html are background files, and C is a background directory. To reinforce what has already been discussed, if we were to modify the background file A/moo.txt, it would become the foreground file A/moo.txt:
If B/C is renamed to B/D, then background subdirectory A/C is automatically renamed to A/D too; put another way, background subdirectories and background files have similar behavior when it comes to tracking renames that occur in a lower layer.
Notice that A now contains a background directory named D.
Transparent subdirectories
When a background object within a transparent directory is modified, it becomes a foreground object. We've seen this for files (e.g.: A/moo.txt became A/moo.txt), but it's also true for subdirectories. For example, within transparent directory A, if we were to add a file to the background subdirectory D (e.g.: hen.html), we'd be modifying A/D. Therefore it must become a foreground subdirectory A/D. Alfresco makes A/D transparent by default, so that you'll continue to track changes in B/D:
The distinction between background subdirectory A/D and transparent subdirectory A/D might seem a bit moot at first because Alfresco makes A/D an overlay on B/D automatically. Thus, when B/D/goat.html is added, it also appears as the background object A/D/goat.html:
Unless someone renames B/D (i.e.: the underlying directory), this somewhat subtle distinction will continue to be moot.
Gotcha: Stale transparent directories
Just like a symlinked directory can point to a directory that is no longer present, a transparent directory (e.g.: A/D) can be an overlay on top of a directory that has been renamed or deleted (e.g.: below, B/D was renamed to B/E). The icon for the transparent directory D is shown in red to indicate this:
Because A/D was an overlay on B/D, but B/D is gone now, the background files within A/D (i.e.: A/D/egg.html and A/D/goat.html) have vanished as well.
Definition:
- Stale transparency
- A transparent object that once overlayed something that is no longer present.
- For example, A/D is stale because it overlays B/D, which once existed, but is now gone.
- Stale transparency
Deleting transparent directories
Just like any other kind of directory, a transparent directory can be deleted, For example, if A/D were deleted, you'd see something like this:
Obviously, deleting a transparent directory removes all it foreground objects (e.g.: A/D/hen.html).
Additions beneath a transparent directory
Earlier, it was shown how files in the directory beneath a transparent directory appear as background files. It was also shown how an attempt to modify a 'background file' creates a foreground file, which hides the background file from view. However, consider the previous figure; transparent directory A already has a file named moo.txt. What happens if a file named moo.txt is added to the underlying directory B? As you can see, the foreground file A/moo.txt still hides B/moo.txt; the fact that B/moo.txt was created later doesn't matter:
Similarly, because A is a transparent layer on top of B, if the subdirectory A/C is created, Alfresco defaults to making it an overlay on B/C, even if B/C doesn't exist yet. To make this example, a bit more interesting, if we were to also create a file named hen.html within A/C, the result would be:
Definition:
- Latent transparency
- A transparent object that overlays something that does not exist yet.
- For example, A/C is a latent transparent directory because it will overlay B/C, once B/C is created.
- Latent transparency
Note that A/C is not stale because B/C has never existed; A/C is merely latent. Nothing is 'broken', so A/C does not appear in red. It's merely pre-configured to maintain the parallel directory structure that already exists between A and B. At this point, if B/C were created containing the file egg.html, the result would be:
Notice how the background file A/C/egg.html has appeared automatically. It does not matter that the transparent directory A/C was created prior to the directory it overlays (i.e.: B/C).
Notice also that Alfresco can tell the difference between a transparent directory overlaying something that has been moved (or deleted), and a transparent directory overlaying something that simply has not been created yet. It can do this because renames and deletions are recorded. Thus, it's easy for the user (and merge scripts) to tell whether an transparent overlay is out of sync with its underlying layer, or simply growing in new directions in advance of its underlying layer.
Transparent directories with opaque subdirectories
By default, when a subdirectory is created within a transparent directory, it too is a transparent directory (e.g.: A/C in the previous example was an overlay on B/C). However, if you wish, you can also create A/C as a normal (opaque) directory; as such, no background directories or files will appear within it:
In the figure above, A/C is represented by a solid yellow folder, not a 'clear' or 'see-through' folder icon. At this point, if B/C were created, and egg.html were placed inside of it, we'd have:
Note that A/C still only contains hen.html; no background file A/C/egg.html, appears. Alfresco's default behavior is simple to remember:
- Within opaque directories, opaque subdirectories are created
- Within transparent directories, transparent subdirectories are created
As you have seen, each of these default behaviors may be overridden.
Transparent Files
If a transparent directory is like a 'sheet of glass' over another directory, a transparent file is like a 'fiber optic cable' to another file. As long as you don't attempt to modify the contents of a transparent file, it behaves very much like a UNIX symlink. Transparent files provide much finer-grained control than transparent directories do. For example, a directory might contain a set of transparent files referencing the contents of more than one directory.
In the figure below, X/yak.txt is a transparent overlay on top of Y/yak.txt, and X/zoo.txt is a transparent overlay on top of Z/zoo.txt:
However, if you attempt to modify the contents of a transparent file, it becomes a normal/opaque file. To illustrate this, if we write to X/yak.txt, the clear box around it (along with its associated annotation) is removed:
Writing to a transparent file is quite different from merely renaming it. For example, if X/zoo.txt were just renamed to X/zebra.txt, it would remain a trasparent overlay on Z/zoo.txt. Changes to the contents of Z/zoo.txt would be visible immediately within X/zoo.txt. Notice in the figure below that X/zebra.txt still points to Z/zoo.txt:
Gotcha: Stale transparent files
Let's rename X/zebra.txt back to X/zoo.txt again:
Just like with a symlink, it's also possible to create a transparent file whose target is missing due to a rename or deletion. For example, in the figure below, Z/zoo.txt has been renamed to Z/zebra.txt:
Notice how X/zoo.txt is now a stale transparent file; the object it once overlayed (Z/zoo.txt) no longer exists. Hence, it's shown using a red font to highlight the problem.
Related Work
Transparent layers in Alfresco are reminiscent of Unionfs; however there are some critical differences:
- Alfresco offers both directory and file-level transparent layering
- Alfresco provides a fully-developed and integrated versioning system