STP/GUILookAndFeelIntegrationProposal

GUI Proposal: XEF and WTP Editor Integration

This proposal provides GUI look and feel for integration of XEF and WTP-based editors.

As it was agreed, integration provides a way to combine the strengths of both editors: use the WTP-based editor to view and edit the policy document as a whole and the XEF editor as a detail editor when fragments in the policy document that contain individual assertions need to be edited.

1. Editing policy document as whole

On the first step user will open(create) policy file (or policy attachment in wsdl) with WTP-based editor. Here it is possible to add/delete new alternatives and assertions, combine and build the hierarchy of them. Additionally, WTP-based policy editor could provide following functionality:

• merge policies;
• intersect polices;
• normalize policy;
• validate policy.

Validation could be used in two modes:

• validate whole policy document;
• propose list with only allowed policy assertions (in GUI).

Draft look&feel of policy document editing is represented bellow:

2. Editing individual assertions

As soon as user chooses editing of individual assertion in WTP-based policy editor (via click on arrow), XEF editor will be activated. XEF editor represents GUI elements accordingly assertion schema. User can change assertion properties, save them and return to editing of whole policy document (via icon in left corner). It is possible to edit more than one assertion in parallel (idea is the same as in editing of WSDL inline schemas).

David Bosschaert: I'm curious how you can edit multiple assertions in parallel, since editing an assertion should go into that particular assertion, which would replace the canvas of the high-level editor with the more detailed one (just like what happens with the WTP XML editor). I don't quite understand how you can edit multiple assertions in parallel that way. Sure you could jump into one assertion, make changes, jump back out to the high-level editor and go into a second assertion, that should work fine. It's just the 'parallel' piece that I don't get yet.

Draft look&feel of individual assertion editing is represented bellow:

David Bosschaert: In many cases the policy assertions within a single alternative are related, so I think it would be good to at least give the details editor access to the other assertions within the same alternative, so you can edit them together. Below you can see a suggestion on how this could look.

Jerry Preissler: Good idea, what about the following changes:

* when switching to the detail editor, display all assertions contained in the compositor (all|exactlyOne) that contains the selected assertion
* directly edit the primitive assertions in the detail editor
* switch back to the overview editor if a contained compositor is selected

If you don't want to see the other alternatives, you can click them away with a special layout button in the editor toolbar. See below:

Andrei Shakirin:

I find your idea very useful, David. But I just not sure how to process following use case: if policy has assertions and alternatives on the same level. Sample:

<wsp:All>
  <!-- assertion 1 -->
  <!-- assertion 2 -->
  <wsp:All> <!-- assertion 3 --> </wsp:All>
  <wsp:ExactlyOne> <!-- assertion 4 --> </wsp:ExactlyOne>
</wsp:All>

I see the following solutions for this use case:

1. Always open and show only one selected assertion in detail editor (this solution also allows to open multiple detail editors for different assertions. Exactly this I mean under "parallel editing"). Disadvantage: it can be annoying to switch between editors to edit individual assertions.
2. Show assertions only on the same level with selected one (assertion1, assertion2) like you represent it on the first screenshoot. Disadvantage: user can be confused about real structure of parent alternative (he doesn't see <All> and <ExactlyOne> child alternatives and enclosed assertions)
3. Show all assertions and alternatives on the same level with selected assertion (assertion1, assertion2, <All>, <ExactlyOne>), but make alternatives(<All> and <ExactlyOne>) not editable and not exposable. Disadvantage: it could be confusing for the user to see policy alternatives in detail editor. It also mixes representation in editors, there is no clear separation any more.

My personal proposal: keep the first iteration as easy as possible. Let implement solution 1 even without support of multiple detailed editors feature, but design interfaces flexible enough to extend this solution on next iteration.

Than we can estimate usability, problematic issues an extend editors correspondingly on the next iterations.

Interface proposal

I suggest to integrate editors on the base of the following public interfaces. IPolicyDetailEditorInput represents input interface for detail policy editor and IPolicyDetailCallback provide callback events for WTP-based editor.

1. Policy detail editor input public interface

/**
 * <b>This interface provides access for input for detail policy editor</b><br>
 */
public interface IPolicyDetailEditorInput extends IEditorInput {

	InputStream getStream();
	
	IProject getProject();
	
	IPolicyDetailCallback getCallback();

	public ISchemaProvider getSchemaProvider();
	
	public Map<String, Object> getProperties();

}

2. Callback interface

/**
 * <b>This interface represents the callbacks of detail policy editor</b><br>
 */
public interface IPolicyDetailCallback {
	
    /**
     * Retrieve context data.
     *
     * @param ctxID Context identifier. 
     * @return Context data.
     */
    Object getData(String ctxID);

    /**
     * Called on save event.
     *
     * @param source Input stream containing updated policy part. 
     * @throws Exception if any error occurs.
     */
    void onSave(final InputStream source) throws Exception;
	
    /**
     * Called on close event.
     */
    void onClose();
	
    /**
     * Called on error event.
     */
    void onError();

}

Invocation of detail policy editor will looks like:

...
AssertionInput assertion = new AssertionInput(name, stream, callback);
EnvironmentInput environment = new EnvironmentInput(project, schemaProvider, props);
IPolicyDetailEditorInput input = new PolicyDetailEditorInput(assertion, environment);
IWorkbenchPage workbenchPage = null; // get workbenchPage
IEditorPart editor = IDE.openEditor(workbenchPage, input, "XEF-Editor-ID");
...

XML Schemas

Processing of individual policy assertion by XEF Editor is based on XML-Schemas. Therefore one of the integration tasks is storing, discovering and providing schemas to XEF Editor.

1. Retrieving schemas by XEF Editor.

XEF Editor will obtain required schemas via internal interface ISchemaProvider:

public interface ISchemaProvider {
    Collection<String> listSchemaNamespaces(String filter);    
    Collection<String> listSnippets(String filter);    
    String getSchema(String namespace);
    String getSnippet(String name);
    void refresh();
}

For the future we will also analyse the possibility to use standard implementation of schema catalogue here.

2. Schemas locations.

I see following possible schemas locations:

1) Eclipse project, where processing policy is located (or dedicated subfolder in this eclipse project).

Schemas could be discovered automatically before creation/edition of ws-policy file

2) File system.

User should specify location of such schemas in GUI before creation/edition of ws-policy file.

3) Remotely stored schemas (http accessable).

Schemas could be retrieved automatically from internet.

4) Default embedded schemas.

Some basic schemas could be delivered with Policy Editor plugin, so user can just use them in ws-policy assertions without any additional configuration activities. Default schemas could be:

  - http://www.w3.org/ns/ws-policy
  - http://schemas.xmlsoap.org/ws/2005/02/rm/policy
  - http://schemas.xmlsoap.org/ws/2005/07/securitypolicy
  - http://schemas.xmlsoap.org/ws/2004/08/addressing
  - http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd
  - http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd

License issues of these schemas should be accepted by Eclipse IP process

5) Standard Eclipse policy catalog

Schemas could be retrieved from Eclipse schema catalog

I suggest to implement 1 and 4 in Ganymede Release. In further releases schema locations could be extended by 2, 3 and 5.