Transparent Layers

[resplin]

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:

transparent_layers_0.png

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:

1. 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
2. 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
     

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.

transparent_layers_1.png

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).

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:

transparent_layers_2.png

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:

transparent_layers_3.png

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

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:

transparent_layers_4.png

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:

transparent_layers_5.png

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:

transparent_layers_6.png

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:

transparent_layers_7.png

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:

transparent_layers_8.png

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:

transparent_layers_9.png

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.

transparent_layers_10.png

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:

transparent_layers_11.png

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:

transparent_layers_12.png

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:

transparent_layers_13.png

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.

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:

transparent_layers_14.png

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:

transparent_layers_15.png

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:

transparent_layers_16.png

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.

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:

transparent_layers_17.png

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:

transparent_layers_18.png

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:

transparent_layers_19.png

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:

transparent_layers_20.png

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:

transparent_layers_21.png

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:

transparent_layers_22.png

Gotcha: Stale transparent files

Let's rename  X/zebra.txt  back to X/zoo.txt again:

transparent_layers_23.png

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:

transparent_layers_24.png

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