RFS Synchronization
Contents |
Synchronizing RFS and VFS
During development it is very useful to synchronize the VFS (the virtual file system of OpenCms, located in the database) with a directory in the RFS (real file system on your disk where you develop stuff).
You will probably not want to develop all files directly within the OpenCms Administration UI. Firstly, because the source editor does not support syntax highlighting. Secondly, because the files in the VFS are outside of your version control system.
That way you can develop files on your disk under version control, within your favourite IDE and use the synchronization function to update the changes within OpenCms. However, if you change Java code, library dependencies or classpath resources, you will have to reload the OpenCms web application or even restart your servlet engine.
A disadvantage of this method is that if you decide to synchronize a directory which is under version control OpenCms will also import any files or folders your SCM software uses to store metadata about your working directory, e.g. .svn and CVS. If that happens, be careful not to delete the folders in the VFS. Otherwise, the next time you start a synchronization, OpenCms will delete them from RFS and thus corrupt your working copy.
Synchronization cache (#synclist.txt)
OpenCms creates a file #synclist.txt in the RFS synchronization folder. It contains names and timestamps of all files of the last synchronization run and is the basis to determine changes when synchronization is called again. You need to take care not to delete this file by mistake when you clean your build. If you do, the next synchronization with OpenCms will not work correctly. You will have to build and synchronize again to get it back working.
How does synchronization work?
If you start synchronization OpenCms will copy all files from all VFS directories part of the synchronization settings to the RFS synchronization directory. It will also copy all files from the RFS to the VFS which are not already there. When a file exists in the VFS and in the RFS, OpenCms will update whichever copy is older. The names and timestamps of all synchronized files are cached in #synclist.txt in the RFS synchronization directory. This speeds up subsequent synchronization runs.
The pathnames that you enter in the synchronization settings are absolute VFS pathnames and must be relative to the given RFS directory.
Example: If you set the RFS synchronization path to
/home/jdoe/checkouts/eshop-module/build/
and set the VFS synchronization path to
/system/modules/com.acme.eshop/
OpenCms expects files and folders in the RFS at
/home/jdoe/checkouts/eshop-module/build/system/modules/com.acme.eshop/.
After synchronization, you can find the synchronization cache file at
/home/jdoe/checkouts/eshop-module/build/#synclist.txt.
How to avoid a synchronization disaster
If you notice that synchronization included files which shouldn't have been copied, do not just delete the files from the RFS. They are listed in the synchronization cache file and would be deleted from the VFS during the next synchronization. To get back to a clean state delete the synchronization cache file as well. This makes sure that the mechanism restarts from the beginning.
To avoid this problem completely you should not synchronize directories which already exist in the initial OpenCms setup. Only synchronize directories that you created and which are part of the build with which you want to synchronize. Otherwise, you will lose files and might need to reinstall OpenCms.
