View source for E4/Resources/Semantic File System/Demos/Running SFS Examples

== Prerequisites  ==

You have an Eclipse IDE with the Semantic File System plug-ins running.<br>The required plug-ins are: 

*org.eclipse.core.resources.semantic 
*org.eclipse.core.resources.semantic.examples
*org.eclipse.ui.resources.semantic 
*org.eclipse.ui.resources.semantic.examples

The IDE used for the below examples was a “Eclipse IDE for Java EE Developers” downloaded from [http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/galileo/SR1/eclipse-jee-galileo-SR1-win32.zip 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 -&gt; Other… (or CTRL-N):

&nbsp;[[Image:SFSDemosNewDemoProjectWizard.jpg]]

On the first page, you will be asked which scenarios you are going to use:<br>[[Image:SFSDemosWizardSelectScenarios.jpg]]<br>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”:<br>[[Image:SFSDemosWizardProjectName.jpg]]<br>After successful completion, there should be a new project in your workspace looking like this: 

[[Image:SFSDemosInitialProjectContent.jpg]]

== Scenarios  ==

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. 

== Scenario: DefaultContentProvider  ==

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.<br>In addition, the DefaultContentProvider allows some basic REST-like Resource management. 

Most of the DefaultContentProvider functionality is explained in [http://wiki.eclipse.org/E4/Resources/Semantic_File_System/GettingStarted#The_DefaultContentProvider GettingStarted]

==== 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:<br>[[Image:SFSDemosSelectLocalFile.jpg]]<br>You may or may not change the value of the “Resource Name” field.<br>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 -&gt; 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.<br>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:<br>[[Image:SFSDemosAddSalesOrder.jpg]]<br>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:<br>[[Image:SFSDemosSalesOrderAdded.jpg]]<br>

== Scenario: SampleCompositeResourceContentProvider  ==

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

==== 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&nbsp;-&gt; "Add a Local File System Resource" menu:<br>[[Image:SFSDemosAddComposite.jpg]]<br>Do the same for the files “test_en.txt” and “test_en_US.text”, respectively. You have now three files under the “SampleCompositeResourceContentProvider” folder.<br>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.<br>Once you refresh the project explorer tree, you should see all three files marked as “checked out” (red decorator):<br>[[Image:SFSDemosCompositeCheckedOut.jpg]]<br>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 -&gt; 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.<br>

==== 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.<br>You can still remove the files from the workspace using “Team -&gt; 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.<br>If the files are not checked-out (for example, because they have been reverted), deletion will happen without the popup.

== Scenario: SampleWebDAVContentProvider  ==

This scenario illustrates the usage of WebDAV resources and the usage of Semantic Resources outside of Semantic Projects. 
It assumes that a WebDAV server has already been set up. In the example below, the server is set up on the same machine as the example (localhost), but in principle, there shouldn't be any differences when working with a remote WebDAV server. 
The underlying content provider implements ISemanticContentProviderREST. The WebDAV URL is stored as a Property in the corresponding node when method addFileFromRemoteByURI() or addFolderFromRemoteByURI() is called. 

=== Adding a WebDAV Resource to a non-Semantic Project  ===

It is possible to add a WebDAV Resource to any project by creating a link to the underlying SFS Resource. Let's assume we have already created a General Project named "GeneralProjectWithWebDAVFolder". Select the project and right-click New -&gt; Other... -&gt; Semantic File System -&gt; WebDAV Resource: 

[[Image:SFSCreateWebDAVResource.jpg]]

After clicking "Next", a dialog will appear for adding the WebDAV information. You need to provide a name for the resource and a WebDAV URL: 

[[Image:SFSEnterWebDAVURL.jpg]]

<br> Note that the type of the resource (file or folder) will be determined automatically. Upon "Next", the URL will be validated. 

[[Image:SFSValidateWebDAVURL.jpg]]

If the URL is invalid, an error message will be shown. It is still possible to create the link when checking the "Ignore URL check results" checkbox. Upon "Finish", the file or folder is created as link. If a folder is created and the "Retrieve WebDAV hierarchy after finish" was checked, the folder's child hierarchy will be automatically fetched from the WebDAV server, otherwise, the child list will be empty; in our example, we have added a folder and checked the "Retrieve" option: 

[[Image:SFSWebDAVFolderCreated.jpg]]

<br>
Note that the retrieved file/folder hierarchy is cached locally so that you can browse through resource tree with the speed of local file system. In order to refresh the hierarchy, you can select the folder or file you want to refresh and then use the menu action found at Team -> Synchronize With Repository.

=== Adding a WebDAV Resource to a Semantic Project  ===

If the WebDAV Resource is added to a Semantic Project, the WebDAV Resource will be created as "normal" Semantic Resource under the project. A Semantic "General" project can be created manually using the following steps: 

#Start the "New Project" wizard and select "General Project"<br> 
#Enter a project name
#Un-check "Use Default Location"
#Choose "Semantic File System" in the dropdown that became active after un-checking "Use Default Location"
#Copy the project name from the "Project name" into the "Location" field (is it strongly recommended to use the same name here in order to avoid overlapping of projects):

[[Image:SFSCreateGemeralSemanticProject.jpg]]

Upon "Finish" the project will appear in the Workspace. You can now add the WebDAV Resource exactly as described above. In our example, we have added a WebDAV file:

[[Image:SFSWebDAVFileCreated.jpg]]

=== Local editing and synchronization ===

When editing a WebDAV file, the changes will not be propagated to the WebDAV server automatically. Instead, the changes will be stored in the SFS. You can simply open a text editor. When starting to type, you will get a popup asking whether the resource should be made writable. If this is confirmed, a red marker will appera on the file indicating that it is "writable".

In order to propagate the changes back to the WebDAV server, you can use the menu action found at Team -> Synchronize With Repository

== Scenario: RemoteStoreContentProvider  ==

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.<br>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.<br>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" -&gt; "Remote Store Editor":<br>[[Image:SFSDemosRemoteStoreEditor.jpg]]<br>You can add and delete folders and files, change file contents or timestamps using this editor (don’t do this yet). 

==== Synchronization  ====

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.<br>You can repeat this with the newly added “First” folder to add the “Second” folder (this works on single level.<br>In order to add the complete “remote” content, open the context menu on the root folder and select “Team -&gt; Synchronize content with Repository”. This will synchronize all items in the “remote” repository.<br>You can delete the synchronized items and repeat the above. 

==== Editing  ====

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):<br>[[Image:SFSDemosChangedLocally.jpg]]<br>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.

==== Synchronization local-&gt;remote  ====

In order to update the “remote” store with the changed content, open the context menu on the file and select “Team -&gt; 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 remote-&gt;local  ====

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).<br>Then synchronize again using Team -&gt; 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:<br>[[Image:SFSDemosNewRemoteFile.jpg]]<br>After completion, the “RemoteStoreEditor” should be updated automatically: 

[[Image:SFSDemosNewFileCreated.jpg]] 

==== Deleting a Remote Resource  ====

This can be done using the context menu on the file. Select “Team -&gt; 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 -&gt; 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&nbsp;-&gt; Diff against Repository state”. You should see a compare view with the changes: 

[[Image:SFSDemosDiffVsRemote.jpg]]

==== 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:<br>[[Image:SFSDemosTeamSynchStart.jpg]]<br>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).<br>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:<br>[[Image:SFSDemosTeamSynchView.jpg]]<br>The synchronization action itself is currently not integrated in the view. However, when you synchronize the file manually (using the “Team -&gt; 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.<br>In order to open the history view, open the context menu on the file and select “Team&nbsp;-&gt; Show Remote History” or open View “History” (under the “Team” category). This is a generic view provided by the team plug-in.<br>For the example file, this might look like this:<br>[[Image:SFSDemosHistoryView.jpg]]<br>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).