STP/Policy Component/Policy editor documentation
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.
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.
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:
<?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>
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 has defaults others are required. They have tooltips and documentation in the policy help view. There are also extra sections with 'Encryption' and 'Advanced' attributes. There are fields that are enumerated (the encryption type) and password fields. 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
wsp:All is supported.
While the policy editor doesn't have to work directly on files, it uses the
org.eclipse.stp.ui.xef.editor.XMLProviderEditorInput as its editing interface. The
XMLProviderEditorInput provides the actual XML to be edited as well as a catalogue of the schemas available.
eclipse.stp.ui.xef.editor.XMLXPathView in the
org.eclipse.stp.xef.test fragment provides a way to edit a file in your project using the policy editor. It opens the Policy Editor using all the
.xsd files in the current project as the policy catalogue.
To open this view select Window | Show View | Other | XML XPath View while having the test fragment loaded. (The reason why this view is in the test fragment is because its really for testing purposes).
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.
<wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy"> <wsp:All/> </wsp:Policy>
(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.
<?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>
Select the file and hit 'Edit' in the XML XPath View:
Then hit 'Add Policy' and you will see the policy in the Policy Catalogue:
Select the policy and you see it appear:
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
xs:choice in the Logging_Basic element.
xs:all are also supported.
After selecting the file sub-element you can see the attributes in their basic form as found in the schema:
The document above can also be seen in XML form in the XML tab:
<?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>
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
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:
- [xef:] - these annotations are, not gui-specific in their nature, but could influence the resulting GUI.
- [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:
The customizations in the screenshot are made as follows:
1. To display a user readable name instead of the default attribute name, put a
<xef:displayname> annotation in the attribute definition:
<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>
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 specify the value in the resulting XML. When an attribute is defined with the XML-Schema
use="required" 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
use="required" is specified.
3. Adding a
<xef:docShort> 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> annotation:
<xs:attribute name="rolling_file" type="xs:boolean"> <xs:annotation> <xs:appinfo> <xefgui:widget>check</xefgui:widget> </xs:appinfo> </xs:annotation> </xs:attribute>
The fully annotated XML Schema document can be found here.
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:
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.