E4/Resources/Semantic File System/GettingStarted
- 1 Prerequisites
- 2 Creating the example project
- 3 A short walk-through: some places to know about when working with the Semantic File System
- 4 Scenarios
- 5 Scenario: DefaultContentProvider
- 6 Scenario: Sample SampleWSDLXSDContentProvider
- 7 Scenario: SampleCompositeResourceContentProvider
- 8 Scenario: RemoteStoreContentProvider
- 8.1 Synchronization
- 8.2 Editing
- 8.3 Synchronization local->remote
- 8.4 Synchronization remote->local
- 8.5 Creating a Remote Resource
- 8.6 Deleting a Remote Resource
- 8.7 Creating and deleting resources in the remote repository
- 8.8 Comparing the local version against the repository version
- 8.9 Team Synchronization support
- 8.10 History Support, Comparing Versions
You have an Eclipse IDE with the Semantic File System plug-ins running.
The required plug-ins are:
The IDE used for the below examples was a “Eclipse IDE for Java EE Developers” downloaded from www.eclipse.org/downloads/download.php. Other Eclipse IDE 3.5 versions using a 5.0 or 6.0 Java runtime should also work, except that the Web Service editors mentioned below are missing.
Creating the example project
Before you can start, you need to create an example project. The wizard can be started using New -> Other… (or CTRL-N):
On the first page, you will be asked which scenarios you are going to use:
Simply hit “Next”. On the second page, you will be asked for a project name and the location of some temporary folder in the local file system that can be used to create example data. The default is the user directory as taken from the Java VM. The exact path of the default value depends on the operating system, and the value can be changed to any directory which is writable (and will not be corrupted by creating example data there). It’s probably a good idea to use a folder with a short name that you can easily remember. In the following, we will use “C:\sfsdemo”:
After successful completion, there should be a new project in your workspace looking like this:
A short walk-through: some places to know about when working with the Semantic File System
Semantic Properties Page
This can be reached from any Semantic Resource by opening the context menu in the project explorer and selecting Properties. On the left hand side, there should be an entry “Semantic Resource”. If you select this, you can inspect some resource properties specific to Semantic Resources, for example for the new demo project:
By right-clicking on any entry, you can copy either the value or the key and the value into the clipboard. If you have selected more than one entry, you can copy all selected entries into the clipboard (keys and values).
This can also be reached from any Semantic Resource by opening the context menu and then sub-menu “Team”. The available menu entries depend on the selected resource:
Semantic File System Preference Page
This shows the location of the database file and the cache root which may be useful if you want to have a look at the actual data in your workspace.
Semantic Content View
The view is refreshed automatically to reflect chnages in the Semantic File System; auto-refresh can be disabled in the view menu.
By right-clicking on a node, you can perform the following actions:
- Delete the node and it's children (if any)
- Forcefully delete the node and it's children
- Open the node in the Properties View
- Copy the node's path into the clipboard
- Open the node in a text editor (file nodes only)
The second option can be helpful to cleanup a corrupt SFS database.
When a node is opened in the Properties View, the same information is shown as described above in the section "Semantic Properties Page".
Team Synchronizer UI
This is currently not fully supported. Please see the description of the RemoteStoreContentProvider below for more details.
Remote History Page
The generic “History” view is found under category “Team”. Depending on whether a certain content provider implements history support, it will show the remote versions for a Semantic File.
The following sections deal with different “scenarios”. Each scenario is used to explain some aspects of the Semantic File System. Technically, these scenarios are realized by different content provider implementations.
The DefaultContentProvider is used for any resources for which no specific content provider is responsible. This is necessary, since the project itself is a Semantic Resource. In other words, the DefaultContentProvider bridges the Semantic File System world and the Local File System world.
In addition, the DefaultContentProvider allows some basic REST-like Resource management.
Local File handling
Local files are handled by the DefaultContentProvider in a transparent manner. For example, the “simulatedRemoteContent.xml” file is handled as local file (the blue decorator indicates this). You can also create a local file as usual by selecting a folder and clicking on New -> File in the context menu. The newly created file can be edited and deleted like any other file, even though it is a Semantic Resource (try it and check the Semantic Properties page mentioned above):
Remote resource handling—Internet URL
Select the “DefaultContentProvider” folder in your project and open the context menu. You should see a menu entry saying “Add Demo REST Resource”. After selecting this, a dialog will show up requesting a name and a URL for the new resource. Enter some arbitrary name, e.g. and an existing (and accessible) URL, for example “time.html” and “http://www.time.org”:
Open the new file with the text editor. You will see some HTML code containing a line like
<title>Welcome To The WWW Clock (beta) - Wednesday 16th of December 2009 9:25:39 AM GMT</title>
If you close and re-open the editor, this line will not change. However, you can retrieve the new content using "Team" -> "Synchronize Content with Remote" on the context menu of the new file:
Afterwards, the line above should have changed.
The default content provider does not support editing of non-local resources, so you cannot change the content of the file.
Remote resource handling—File System URI
The DefaultContentProvider is also able to deal with File URIs. Open the context menu on the folder and select “Add a Local File System Resource”. On the dialog, choose “File” and the path to an existing file, for example “aaa.txt” in the “composites” subfolder of the temporary folder, in our example:
You may or may not change the value of the “Resource Name” field.
After completion, you will see a new file under the DefaultContentProvider folder (with the name provided in the “Resource Name” field in the wizard. Similar to the last example, it cannot be edited. However, you could change the file with a text editor in its original location. If you then use Team -> Synchronize Content, the new content will appear in the Semantic File.
Scenario: Sample SampleWSDLXSDContentProvider
This content provider demonstrates the “Semantic” part of the Semantic File System. When adding a Web Service Description Language (WSDL) file, it will scan the contents and automatically add XML Schema Definition (XSD) files that are referenced in the WDSL.
Open the context menu on the SampleWSDLXSDContentProvider folder and select “Add a WSDL Resource”. In the subsequent dialog, select the option “File” and then pick a WSDL file as found in the “mimes” folder, in our example:
After completion, you will not only see this file in the resource tree, but also the required XSDs (address.xsd and customer.xsd). If you have a WSDL editor, you can of course show these files in this editor:
This scenario demonstrates handling of “composite” resources. The underlying content provider considers all files with the same “base name” and extension as part of a composite. The “base name” is extracted from the file name by splitting the name at the underscore character. This is similar to the resource bundle loading behavior.
Even though the composite resource consists of several files which can be updated separately, certain operations can only be performed on the composite as a whole, for example, deletion and check-out (thus ensuring consistency between the different parts of the composite).
Actions on the composite
In order to demonstrate this, add the “test.txt” file from the “composites” sub-folder of the temporary folder to the “SampleCompositeResourceContentProvider” folder using the context menu -> "Add a Local File System Resource" menu:
Do the same for the files “test_en.txt” and “test_en_US.text”, respectively. You have now three files under the “SampleCompositeResourceContentProvider” folder.
Open any of the three files with the text editor and change the text. The content provider will mark all three files as checked-out silently.
Once you refresh the project explorer tree, you should see all three files marked as “checked out” (red decorator):
You can now store the changes. The “checked-out” state is stored persistently along with the resources in SFS metadata (you can use the Semantic Properties page to verify this (the Read-Only flag is false).
Reverting the changes
You can revert the changes (i.e. drop the local changes and re-synchronize with the remote data using “Team -> Revert to Repository State” on the file context menu. The action is available on all three files, but will act on all of them no matter on which of the files it is being called.
Removing the files from the workspace
The “normal” delete action is not supported by this content provider. Unfortunately, it is currently not possible to transport a meaningful message through the call stack, so the “normal” delete operation will simply fail.
You can still remove the files from the workspace using “Team -> Remove from Workspace”. If the resources are marked as “checked-out”, a popup will be displayed indicating possible data loss (the checked-out resources may not have been synchronized with the remote repository. On confirmation, all three files will be deleted.
If the files are not checked-out (for example, because they have been reverted), deletion will happen without the popup.
This scenario simulates a hierarchical “remote” store which contains files and folders. The content provider can interact with this store to synchronize the file/folder hierarchy and content.
The “remote” store is simulated by the XML file named “simulatedRemoteContent.xml” in the demo project. You can use a text or XML editor to inspect the file. It uses a very simple XML schema to store the hierarchy and content.
There is also an editor that is able to display and manipulate the “remote” content. Open the context menu on the XML file and select "Open With" -> "Remote Store Editor":
You can add and delete folders and files, change file contents or timestamps using this editor (don’t do this yet).
In order to start with this scenario, open the context menu on the “RemoteStoreContentProvider” folder and select “Add Resource From Remote”. A dialog should appear offering the top-level elements of the “remote” store for adding. Select one or all and press “Ok”. Upon completion, the selected items should appear under the “RemoteStoreContentProvider” folder.
You can repeat this with the newly added “First” folder to add the “Second” folder (this works on single level.
In order to add the complete “remote” content, open the context menu on the root folder and select “Team -> Synchronize content with Repository”. This will synchronize all items in the “remote” repository.
You can delete the synchronized items and repeat the above.
When you start editing and save a synchronized file, the “local” copy is different from the “remote” copy (you can use the Remote Store Editor mentioned above to inspect the remote content):
You will also notice a red decorator in the project explorer (you may need to hit “Refresh” to make it visible) indicating that the file is no longer read-only.
In order to update the “remote” store with the changed content, open the context menu on the file and select “Team -> Synchronize with Repository”. Since the “local” content is newer than the “remote” content, the remote store will be updated (the RemoteStoreEditor should be updated automatically).
Synchronization can work in both ways: change the file content in the remote store editor (open the context menu on the “File1” tree item and select “Change Content”, enter a new text and save).
Then synchronize again using Team -> Synchronize with Repository”. The content of the text editor should be updated automatically, since the timestamp of the “remote” store is newer than the local timestamp.
Creating a Remote Resource
This demonstrates creation of new remote content: open the context menu on the “First” folder and select “Create a Remote Resource”. On the dialog, chose “File” and enter some content:
After completion, the “RemoteStoreEditor” should be updated automatically:
Deleting a Remote Resource
This can be done using the context menu on the file. Select “Team -> Delete in Repository”. After completion, the text editor will be closed and the deletion should be reflected in the Remote Store Editor.
Creating and deleting resources in the remote repository
If you create files/folders in the remote repository using the Remote Store Editor, you can propagate these changes into the demo project by synchronizing the root folder (“Team -> Synchronize with Repository”, don’t forget to save the XML).
Comparing the local version against the repository version
Save the “First/Second/File1” file again with some changed content. Then open the context menu and select “Team -> Diff against Repository state”. You should see a compare view with the changes:
Team Synchronization support
Team Synchronization is not yet fully supported. You can, however, get an overview of the resources that require synchronization. Open the “Team Synchronizing” perspective:
Click on the little icon above the “Synchronize” tab, select the “Semantic File System” configuration wizard and complete this wizard (choose two-way compare which is also the default).
Upon completion, you should see the file which is out-of-sync with the remote repository. If you double-click it, you will see again the compare view:
The synchronization action itself is currently not integrated in the view. However, when you synchronize the file manually (using the “Team -> Synchronize with Repository” context menu, the entry above should disappear from the Team Synchronization view (press F5 on the “Synchronize” tab for refreshing it).
History Support, Comparing Versions
The RemoteStoreContentProvider also supports remote versions. Whenever the (remote) content of a file is changed, a copy of this content is stored away with a timestamp.
In order to open the history view, open the context menu on the file and select “Team -> Show Remote History” or open View “History” (under the “Team” category). This is a generic view provided by the team plug-in.
For the example file, this might look like this:
Using the context menu, you can open a compare view of the file against the locally synchronized version (if you select two entries from this list, you can also do a three-way compare).