Skip to main content
Jump to: navigation, search

STP/Policy Component/Policy editor documentation

< STP‎ | Policy Component
Revision as of 07:03, 27 August 2007 by Davidb.iona.com (Talk | contribs) (Further Customizations)

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.

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:

<?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.

Quick start

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.

The 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:

Shot3.jpg

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

Shot4.jpg

Select the policy and you see it appear:

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 xs:choice in the Logging_Basic element. xs:sequence and 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:

Shot2.jpg

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

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: 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:

Shot1-2.jpg

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:

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.

Copyright © Eclipse Foundation, Inc. All Rights Reserved.