View source for STP/Policy Component/Policy editor documentation

&larr;[[STP_Component_Catalog | Back to STP Component Catalog ]]
=The STP Policy Editor and XEF (Xml Editing Framework)=
The STP policy editor is an Eclipse editor for editing WS-Policy content or other XML content that is based on XML-Schema with a graphical editor. It is based on the XML Editing Framework (XEF), which also part of STP.

The code of the policy editor can be found in the STP CVS system in the org.eclipse.stp.xef plugin (/cvsroot/stp/org.eclipse.stp.servicecreation/org.eclipse.stp.xef). The unit tests are in the org.eclipse.stp.xef.test fragment. 

==What kind of policies can be edited==
The simplest way to use the policy editor is on a file in the Eclipse workspace. In the example below you can see the policy editor being used on a file called 'myService.policies'. The file contains a logging and a security policy.

[[Image:shot1.jpg]]

The policy editor dynamically generates an editor as the above one that can be used to edit policies. It provides both a graphical view as well as a text-based view of the policy document being edited.

The editor in the example above is editing the following XML:
<code><pre><?xml version="1.0" encoding="UTF-8"?>
<wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
  <wsp:All>
    <acme:Logging xmlns:acme="http://www.acme.com/xsd/2007/08/logging">
      <file encryption_password="edcba" encryption_type="DES" filename="myService.log" rolling_file="true" />
    </acme:Logging>
    <acme:Security xmlns:acme="http://www.acme.com/xsd/2007/08/security" />
  </wsp:All>
</wsp:Policy></pre></code>

In this example, the Logging and Security policy are based on their XML Schema definitions and the policy editor has created the editor dynamically by reading the Schema definitions. By looking at the editor, you can see that the policies document currently contains 2 policies: Logging and Security. The logging policy has a sub-element called 'file'.

The file element has a number of attributes, some of which have defaults while others are required. They have tooltips and documentation in the policy help view. There are also extra sections with attributes that relate to 'Encryption' and 'Advanced' items. There are fields that are enumerated (the encryption type) and password fields. The password fields can process values before they are stored in the XML (in this example the 'ReverseTextFilter' example filter is used that simply reverses the string, but applications could use secure hashing or encryption techniques to process sensitive data before it is stored in the XML). Some fields have their units of measurement specified (the kb. field) and all of them have proper display names. The following section provides a quick start to getting here.

The resulting XML file in this example is a WS-Policy compliant document. However note that currently not all of the WS-Policy constructs are supported yet. Currently only <code>wsp:All</code> is supported.

==Quick start==
The policy editor doesn't have to work directly on files. It uses the <code>org.eclipse.stp.ui.xef.editor.XMLProviderEditorInput</code> as its editing interface. The <code>XMLProviderEditorInput</code> provides the actual XML to be edited as well as a catalogue of the schemas available.

The <code>eclipse.stp.ui.xef.editor.XMLXPathView</code> in the <code>org.eclipse.stp.xef.test</code> fragment provides a way to edit a file in your project using the policy editor. It opens the Policy Editor using all the <code>.xsd</code> files in the current project as the policy catalogue. (The reason why this view is in the test fragment is because its really for testing purposes, product code should work with the <code>XMLProviderEditorInput</code>).

To open this view select Window | Show View | Other | XML XPath View while having the test fragment loaded. 

To start with an empty policy file, create a file, e.g. myService.policies with the following initial content, which really is an empty WS-Policy document.
<code><pre><wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
    <wsp:All/>
</wsp:Policy></pre></code>
(BTW it would be a nice addition if an empty file would work here too). 

Also make sure to have with the following schema for the logging policy in your project. It's called Logging_Basic (in the file acme_logging_basic.xsd) as it is just the basic schema. Some of the GUI elements in the previous screenshot have been influenced by annotations. Below you can find the basic schema to start with without these annotations.

<code><pre><?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
  xmlns:xef="http://schemas.eclipse.org/stp/xsd/2006/05/xef"
  xmlns:xefgui="http://schemas.eclipse.org/stp/xsd/2006/05/xef/gui"
  targetNamespace="http://www.acme.com/xsd/2007/08/logging_basic" 
  xmlns:tns="http://www.acme.com/xsd/2007/08/logging_basic">
		
  <xs:complexType name="fileLoggingType">
    <xs:attribute name="filename" type="xs:string" use="required"/>
    <xs:attribute name="echo" type="xs:boolean" default="false"/>
    <xs:attribute name="rolling_file" type="xs:boolean"/>
    <xs:attribute name="max_size" type="xs:integer" default="50000"/>
    <xs:attribute name="encryption_type">
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:enumeration value="none"/>
          <xs:enumeration value="AES"/>
          <xs:enumeration value="DES"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
    <xs:attribute name="encryption_password" type="xs:string" use="required"/>
    <xs:attribute name="write_interval" type="xs:integer" default="10000"/>
  </xs:complexType>
		
  <xs:element name="Logging_Basic">
    <xs:complexType>		
      <xs:choice>
        <xs:element name="file" type="tns:fileLoggingType"/>
        <xs:element name="console"/>
      </xs:choice>
    </xs:complexType>
  </xs:element>		
</xs:schema></pre></code>

Select the file and hit 'Edit' in the XML XPath View:

[[Image:Shot3.jpg]]

Then hit 'Add Policy' and you will see the policy in the Policy Catalogue:

[[Image:Shot4.jpg]]

Select the policy and you see it appear:

[[Image:Shot5.jpg]]

From the little '''''plus''''' sign on the policy you can see that there are extra elements. Right-click and you can choose from ''file'' and ''console''. These are taken from the <code>xs:choice</code> in the Logging_Basic element. <code>xs:sequence</code> and <code>xs:all</code> are also supported.

After selecting the ''file'' sub-element you can see the attributes in their basic form as found in the schema:

[[Image:Shot2.jpg]]

The document above can also be seen in XML form in the XML tab:
<code><pre><?xml version="1.0" encoding="UTF-8"?>
<wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy">
  <wsp:All>
    <acme:Logging_Basic xmlns:acme="http://www.acme.com/xsd/2007/08/logging_basic">
      <file filename="myService.log" encryption_type="DES" encryption_password="abcde" rolling_file="true" />
    </acme:Logging_Basic>
  </wsp:All>
</wsp:Policy></pre></code>

In this basic form, the following can already be observed.
* Elements with a default provided in the schema have a default button (D). When the default is selected the default value is visible in grey in the controls. When default is selected the value will not be put in the resulting XML (as it can be inferred from the schema). Required elements don't have a default button and need to be filled in.
* Radio buttons are being used for boolean values.
* Spinner controls are used for numeric values.
* Enumerated String attributes

===Further Customizations===
The policy editor can be further customized by adding annotations to the XML-Schema. 
For a full reference of all the available annotations see the following XML-Schema documents:
* [[http://dev.eclipse.org/svnroot/stp/org.eclipse.stp.policy/trunk/org.eclipse.stp.xef/schema/xef.xsd xef:]] - these annotations are, not gui-specific in their nature, but could influence the resulting GUI.
* [[http://dev.eclipse.org/svnroot/stp/org.eclipse.stp.policy/trunk/org.eclipse.stp.xef/schema/xefgui.xsd xefgui:]] - these annotations are gui-specific.

This screen shot notes all the customizations made through annotations and the use of other schema features to realize what was shown in the first screenshot:

[[Image:Shot1-2.jpg]]

The customizations in the screenshot are made as follows:

1. To display a user readable name instead of the default attribute name, put a <code><xef:displayname></code> annotation in the attribute definition:
<code><pre>    <xs:attribute name="filename" type="xs:string" use="required">
      <xs:annotation>
        <xs:appinfo>
          <xef:displayName>File name</xef:displayName>
        </xs:appinfo>
      </xs:annotation>      
    </xs:attribute></pre></code>

2. Optional attributes will get a default button beside them. Pressing the default button will show the default as specified in the XML-Schema in grey in the control and will not actually put the value in the resulting XML. When an attribute is defined with the XML-Schema <code>use="required"</code> there will not be a default button and the user is not allowed to save the editor until the value is filled in. See the previous code snipped of a full attribute declaration where <code>use="required"</code> is specified.

3. Adding a <code><xef:docShort></code> annotation to an attribute will set the tooltip of the control associated with that attribute.

4. Boolean attributes are by default rendered as a set of radio buttons. They can also be rendered as a check box. To do this add the <code><xefgui:widget>check</xefgui:widget></code> annotation:
<code><pre>    <xs:attribute name="rolling_file" type="xs:boolean">
      <xs:annotation>
        <xs:appinfo>
          <xefgui:widget>check</xefgui:widget>
        </xs:appinfo>
      </xs:annotation>      
    </xs:attribute></pre></code>

5. The default as specified in the XML-Schema shines through in grey in the control if the default button is selected. This default value will ''not'' be put in the actual XML, so the entity that processes the XML should read this default from the XML-Schema or obtain it by creating a post-validation infoset (PVI). This example was created using: <code><xs:attribute name="max_size" type="xs:integer" default="50000"/></code>

6. Units of measurement can be specified for a particular attribute. This aids the user with filling in the value. This is done with the <code><xef:units></code> annotation. Example:
<code><pre>    <xs:attribute name="max_size" type="xs:integer" default="50000">
      <xs:annotation>
        <xs:appinfo>
          <xef:displayName>Max file size</xef:displayName>
          <xef:units>kb.</xef:units>
        </xs:appinfo>
      </xs:annotation>            
    </xs:attribute>  </pre></code>

7. A drop-down box with values pre-filled is obtained by creating an attribute that is based on a XSD string type, but restricts it to a fixed number of values through <code><xs:enumeration></code> tags. The drop-down list box shown is created by the following XML Schema definition.
<code><pre>    <xs:attribute name="encryption_type">
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:enumeration value="none"/>
          <xs:enumeration value="AES"/>
          <xs:enumeration value="DES"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute></pre></code>

8. Passwords can be hidden from the user through the use of a password widget <code><xefgui:widget>password</xefgui:widget></code>. A password filter can also be installed that transforms the password before it is put in the actual XML. E.g. it could be using some sort of secure hashing algorithm on the entered value before the password is stored in the XML file. New password filters are installed by implementing an Eclipse Extension point that is exposed by the policy editor. The following example uses the 'ReverseTextFilter' that is part of the test fragment.
<code><pre>    <xs:attribute name="encryption_password" type="xs:string" use="required">
      <xs:annotation>
        <xs:appinfo>
          <xef:filter>ReverseTextFilter</xef:filter>
          <xefgui:widget>password</xefgui:widget>
        </xs:appinfo>
      </xs:annotation>            
    </xs:attribute></pre></code>

9. Sub-elements can be added to the main policy element by right-clicking on the main element. The availability of sub-elements is shown to the user through a 'plus' on the policy icon (see an earlier screenshot on this page). The policy editor will adhere to <code><xs:choice></code>, <code><xs:sequence></code> or <code><xs:all></code> for presenting sub-elements to the user. The reason that there currently is no 'plus' sign on the policy any more is that this element has a an <code><xs:choice></code> section which means that only one sub-element can be used, in this case this sub element is already chosen: the 'file' sub-element. Example:
<code><pre><xs:element name="Logging">
    <xs:complexType>    
      <xs:choice>
        <xs:element name="file" type="tns:fileLoggingType"/>
        <xs:element name="console">
        </xs:element>
      </xs:choice>
    </xs:complexType>
  </xs:element></pre></code>

10. Policy documentation is obtained from the standard <code><xs:documentation></code> annotation, which can be put both on elements as well as attributes. The documentation will be visible in the 'Policy Help' view which can be opened by clicking the question mark icon on the policy editor (top-right), by right-clicking 'help' on a policy element or simply directly from the Eclipse 'Show View' dialog. The help text can contain plain text as well as HTML markup.

11. Collapsible subsections (twisties) help organize attributes into groups and can be put around a number of attributes by giving them a category annotations. The current schema has 2 categories for attributes, one called 'Encryption' and another one called 'Advanced'. Example:
<code><pre>    <xs:attribute name="encryption_type" type="xs:string">
      <xs:annotation>           
        <xs:appinfo>
          <xef:category>Encryption</xef:category>
        </xs:appinfo>
      </xs:annotation>            
    </xs:attribute></pre></code>

The fully annotated XML Schema document can be found [[http://wiki.eclipse.org/STP/Full_logging_xsd here]].

XEF editor reference here: http://wiki.eclipse.org/STP/XEF_Reference .

= What is XEF =
XEF is a mechanism for editing XML content using a widget-based Editor (with various kinds of controls, tooltips, dynamic help and other features). The editor provided by XEF is dynamically synthesized based on the XML Schema that defines the XML. XEF is the technology that underpins the Policy Editor and is itself also part of STP.

Logically XEF works like this: 

[[Image:XEF.jpg]]
 
Input to the editor is the current XML (of the piece of XML that is being edited) and the Schema(s) on which this XML is based. The output is XML that adheres to the schemas. 
Use of standard XML-Schemas is fine, although the widgets on the generated editor can be tweaked by annotations/appinfo sections in the XML-Schema. 
In short, XEF should allow you to create a Eclipse editor for any piece of XML without writing Eclipse GUI code, as long as the XML is defined by a Schema.

= Compatibility =
The <code>org.eclipse.stp.xef</code> plugin is compatible with Eclipse 3.2 and upwards. 
However the testing fragment (<code>org.eclipse.stp.xef.test</code>) requires Eclipse 3.3 for the XMLXPathView class. This class is not used by the JUnit tests, but facilitates the playing with the XEF editor.
To run the JUnit tests in a 3.2 environment, you can temporarily remove this class and then run the AllTests suite.

= XEF Dependencies =
The XEF editor depends on the following plugins (outside of the eclipse core):
<pre>org.apache.xerces
org.eclipse.stp.policy.common
org.eclipse.wst.common.uriresolver
org.eclipse.wst.sse.core
org.eclipse.wst.sse.ui
org.eclipse.wst.xml.core
org.eclipse.wst.xml.ui</pre>
The org.eclipse.stp.policy.common plugin is part of the same component in STP. The easiest way to get all these dependencies is to install the 'Eclipse XML Editors and Tools' from the Web & JEE Development component + all its dependencies:
[[Image:xef_deps.JPG]]

Then you can can simply check out the
<pre>org.eclipse.stp.policy.common
org.eclipse.stp.xef</pre> in your project or get them from an update site:
[[Image:xef_projects.JPG]]

Now you are all set and ready to use the XEF editor.


= Running the XEF unit tests =

All of the XEF unit tests are in the <code>org.eclipse.stp.xef.test</code> fragment. These tests can be run individually, but if you want to run them all you can run the <code>org.eclipse.stp.xef.tests.AllTests</code> testsuite. This class is required by the automated build system to run all the tests, but can also be used from within Eclipse to run all the tests in one go.

[[Image:xef_allok.JPG]]

= STP Policy Meetings =
{| class="wikitable" border="1" style="width:75%;"
|-
! Meeting Date & Agenda
! Minutes
|-

|- 
| [[STPPolicyMeetingAgendaNov22th |  STP Policy Meeting November 22d 2007]]
| [[MinutesNov22 | Minutes]]
|-
|}


= XEF and WTP Editors Integration =

[[http://wiki.eclipse.org/STP/GUILookAndFeelIntegrationProposal | GUI look and feel integration proposal]]