Runtime

## org.eclipse.gmf.runtime.diagram.ui.editpolicies
Class CanonicalEditPolicy

    java.lang.Object
      org.eclipse.gef.editpolicies.AbstractEditPolicy
          org.eclipse.gmf.runtime.diagram.ui.editpolicies.CanonicalEditPolicy

All Implemented Interfaces:
  EditPolicy, NotificationListener, RequestConstants

public abstract class CanonicalEditPolicy
extends AbstractEditPolicy
implements NotificationListener

The base canonical editpolicy class. This edit policy will register itself with the model server to receive semantic events fired to its host editpart. It will create, if necessary, notation elements for all semantic elements inserted into the host element or delete the notation element for the semantic element removed from the host element.

This editpolicy will create the necessary notation element by simply returning a `CreateCommand`.

See Also:
  `CanonicalEditPolicy.refreshSemanticChildren()`, `will create or delete notation elements as required.`, `CanonicalEditPolicy.getCreateViewCommand(CreateRequest)`, `CanonicalEditPolicy.shouldDeleteView(View)`

Nested Class Summary
`protected static class` `CanonicalEditPolicy.CanonicalElementAdapter` Adds `String.class adaptablity to return a factory hint.`

Field Summary

Fields inherited from interface org.eclipse.gef.EditPolicy
`COMPONENT_ROLE, CONNECTION_BENDPOINTS_ROLE, CONNECTION_ENDPOINTS_ROLE, CONNECTION_ROLE, CONTAINER_ROLE, DIRECT_EDIT_ROLE, GRAPHICAL_NODE_ROLE, LAYOUT_ROLE, NODE_ROLE, PRIMARY_DRAG_ROLE, SELECTION_FEEDBACK_ROLE, TREE_CONTAINER_ROLE`

Fields inherited from interface org.eclipse.gef.RequestConstants
`REQ_ADD, REQ_ALIGN, REQ_ALIGN_CHILDREN, REQ_CLONE, REQ_CONNECTION_END, REQ_CONNECTION_START, REQ_CREATE, REQ_CREATE_BENDPOINT, REQ_DELETE, REQ_DELETE_DEPENDANT, REQ_DIRECT_EDIT, REQ_MOVE, REQ_MOVE_BENDPOINT, REQ_MOVE_CHILDREN, REQ_OPEN, REQ_ORPHAN, REQ_ORPHAN_CHILDREN, REQ_RECONNECT_SOURCE, REQ_RECONNECT_TARGET, REQ_RESIZE, REQ_RESIZE_CHILDREN, REQ_SELECTION, REQ_SELECTION_HOVER`

Constructor Summary
`CanonicalEditPolicy()`

Method Summary
`void` `activate()` Registers with the model server to receive semantic events targeted to the host editpart.
`protected boolean` `addListenerFilter(java.lang.String filterId, NotificationListener listener, EObject element)` Adds a listener filter by adding the given listener to a passed notifier.
`protected boolean` `addListenerFilter(java.lang.String filterId, NotificationListener listener, EObject element, EStructuralFeature feature)` Adds a listener filter by adding the given listener to a passed notifier.
`protected java.util.List` `cleanCanonicalSemanticChildren(java.util.Collection viewChildren, java.util.Collection semanticChildren)` Synchronizes the semanticChildren the viewChildren to discover if any of the semanticChildren don't have a corresponding view.
`protected java.util.List` `createViews(java.util.List eObjects)` Creates a `View` element for each of the supplied semantic elements.
`void` `deactivate()` Unregisters all registered model server listeners.
`protected boolean` `deleteViews(java.util.Iterator views)` Deletes a list of views.
`void` `enableRefresh(boolean enable)` Disables the editpolicy.
`protected void` `executeCommand(Command cmd)` Executes the supplied command inside an `unchecked action`
`protected CanonicalStyle` `getCanonicalStyle()` gets the canonical style that may be installed on the host shape compartment view.
`protected Command` `getCreateViewCommand(CreateRequest request)` Returns a `CreateCommand` for each view descriptor contained in the supplied request without forwarding create requests to the host editpart.
`protected ICommand` `getCreateViewCommand(CreateViewRequest.ViewDescriptor descriptor)`
`protected CreateViewRequest` `getCreateViewRequest(java.util.List descriptors)` Return a create view request.
`protected java.lang.String` `getDefaultFactoryHint()` Returns the default factory hint.
`protected Command` `getDeleteViewCommand(View view)` gets a `Command` to delete the supplied `View`.
`protected java.lang.String` `getFactoryHint(IAdaptable elementAdapter)` Clients may override this method to return an appropriate factory hint for the supplied semantic element.
`protected java.lang.String` `getFactoryHint(IAdaptable elementAdapter, java.lang.String defaultHint)` Return a factory hint to assign to this element.
`static java.util.List` `getRegisteredEditPolicies(EObject element)` Returns the `Canonical EditPolicies` mapped to the supplied element.
`static java.util.List` `getRegisteredEditPolicies(EObject element, java.lang.Class clazz)` Returns the enabled `Canonical EditPolicies` mapped to the supplied element that are an instance of the supplied `clazz`.
`protected abstract java.util.List` `getSemanticChildrenList()` Return the host's semantic children.
`EObject` `getSemanticHost()` Return the semantic element to be listened to by this editpolicy.
`protected java.util.List` `getViewChildren()` Return the host's model children.
`protected CreateViewRequest.ViewDescriptor` `getViewDescriptor(EObject element)` Convenience method to create a view descriptor.
`protected CreateViewRequest.ViewDescriptor` `getViewDescriptor(IAdaptable elementAdapter, java.lang.Class viewKind, java.lang.String hint, int index)` Return a view descriptor.
`EditPartViewer` `getViewer()`
`protected int` `getViewIndexFor(EObject semanticChild)` This method tries to locate the position that the view will be inserted into it's parent.
`protected java.util.List` `getViewReferers(EObject element)` Return a list of all the notation elements mapped to the supplied semantic element.
`protected void` `handleNotificationEvent(Notification event)` Handles `NotificationEvent` and resynchronizes the canonical container if the event should be handled.
`protected IGraphicalEditPart` `host()`
`boolean` `isActive()` check is this edit policy is active or not
`boolean` `isEnabled()` Return `true` if the editpolicy is enabled and its host is visible; otherwise `false`.
`protected boolean` `isHostStillValid()` Return `true` if the host is active and its view has not been deleted; otherwise `false`
`protected void` `makeViewsImmutable(java.util.List createdViews)` Sets views as being immutable, meaning that they are unmodifiable as non-persisted views.
`protected void` `makeViewsMutable(java.util.List createdViews)` Sets state on views to allow for modification without changing their non-persisted status.
`void` `notifyChanged(Notification notification)` Event callback: filters out non IElementEvent events.
`protected void` `postProcessRefreshSemantic(java.util.List viewDescriptors)` Allow for post processing of the refresh semantic to set the view mutable state and allow subclasses to add functionality.
`void` `refresh()` Resynchronize the canonical container.
`protected void` `refreshOnActivate()` Refresh that is called on activate of the editpolicy to ensure that all relevant editparts can receive canonically created connections.
`protected void` `refreshSemantic()` Redirects the call to `CanonicalEditPolicy.refreshSemanticChildren()`.
`protected java.util.List` `refreshSemanticChildren()` Updates the set of children views so that it is in sync with the semantic children.
`protected void` `removeListenerFilter(java.lang.String filterId)` Removes a listener previously added with the given id
`protected EObject` `resolveSemanticElement()` Convenience method to return the host's semantic element.
`void` `setEnable(boolean enable)` Sets enable(aBoolean) on all the edit policies of the semantic host.
`void` `setHost(EditPart host)` Asserts that the supplied host is an `IGraphicalEditPart` instance.
`protected boolean` `shouldDeleteView(View view)` returns `true` to always delete a view if required.
`protected boolean` `shouldHandleNotificationEvent(Notification event)` Determines if the the `NotificationEvent` should be handled / processed by the editpolicy.

Methods inherited from class org.eclipse.gef.editpolicies.AbstractEditPolicy
`debugFeedback, eraseSourceFeedback, eraseTargetFeedback, getCommand, getHost, getTargetEditPart, showSourceFeedback, showTargetFeedback, toString, understandsRequest`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### CanonicalEditPolicy

    public CanonicalEditPolicy()

Method Detail

### getRegisteredEditPolicies

    public static java.util.List getRegisteredEditPolicies(EObject element)

  Returns the `Canonical EditPolicies` mapped to the supplied element. Canonical EditPolicies are mapped to their `CanonicalEditPolicy.getSemanticHost()` as the key. A single key may have multiple editpolicies registered against it.

  Parameters:
    `element` - a semantic element
  Returns:
    a unmodifiable list of semantic editpolicies listening to the supplied element

### getRegisteredEditPolicies

    public static java.util.List getRegisteredEditPolicies(EObject element,
                                                           java.lang.Class clazz)

  Returns the enabled `Canonical EditPolicies` mapped to the supplied element that are an instance of the supplied `clazz`. Canonical EditPolicies are mapped to their `CanonicalEditPolicy.getSemanticHost()`as the key. A single key may have multiple editpolicies registered against it.

  Parameters:
    `element` - a semantic element
    `clazz` - a class type
  Returns:
    an unmodifiable list of semantic editpolicies listening to the supplied element

### setHost

    public void setHost(EditPart host)

  Asserts that the supplied host is an `IGraphicalEditPart` instance.

  Specified by:
    `setHost` in interface `EditPolicy`

### host

    protected final IGraphicalEditPart host()

  Returns:
    `(IGraphicalEditPart)host()`.

### getSemanticChildrenList

    protected abstract java.util.List getSemanticChildrenList()

  Return the host's semantic children.

  Returns:
    a list of semantic children.

### getDefaultFactoryHint

    protected java.lang.String getDefaultFactoryHint()

  Returns the default factory hint.

  Returns:
    `host().getView().getSemanticType()`

### getFactoryHint

    protected java.lang.String getFactoryHint(IAdaptable elementAdapter,
                                              java.lang.String defaultHint)

  Return a factory hint to assign to this element. The supplied default hint is used if no hint can be found.

  Parameters:
    `elementAdapter` - adapter that adapts to `EObject`.
    `defaultHint` - a default factory hint (typically the host's factory hint).
  Returns:
    a factory hint.
  See Also:
    `CanonicalEditPolicy.getFactoryHint(IAdaptable)`

### getFactoryHint

    protected java.lang.String getFactoryHint(IAdaptable elementAdapter)

  Clients may override this method to return an appropriate factory hint for the supplied semantic element. Returning `null` will set the factory hint to the host editpart's factory hint.

  Parameters:
    `elementAdapter` - adapter that adapts to `EObject`.
  Returns:
    `null`.
  See Also:
    `CanonicalEditPolicy.getFactoryHint(IAdaptable, String)`

### deleteViews

    protected final boolean deleteViews(java.util.Iterator views)

  Deletes a list of views. The views will be deleted `iff` their semantic element has also been deleted.

  Parameters:
    `views` - an iterator on a list of views.
  Returns:
    `true` if the host editpart should be refreshed; either one one of the supplied views was deleted or has been reparented.

### getDeleteViewCommand

    protected Command getDeleteViewCommand(View view)

  gets a `Command` to delete the supplied `View`.

  Parameters:
    `view` - view to use
  Returns:
    command

### shouldDeleteView

    protected boolean shouldDeleteView(View view)

  returns `true` to always delete a view if required.

  Parameters:
    `view` - to consider
  Returns:
    true or false

### getViewReferers

    protected java.util.List getViewReferers(EObject element)

  Return a list of all the notation elements mapped to the supplied semantic element.

  Parameters:
    `element` - to use
  Returns:
    list of `View`s

### getViewIndexFor

    protected int getViewIndexFor(EObject semanticChild)

  This method tries to locate the position that the view will be inserted into it's parent. The position is determined by the position of the semantic element. If the semantic element is not found the view will be appended to it's parent.

  Parameters:
    `semanticChild` -
  Returns:
    position where the view should be inserted

### createViews

    protected final java.util.List createViews(java.util.List eObjects)

  Creates a `View` element for each of the supplied semantic elements.

  Parameters:
    `eObjects` - list of semantic element
  Returns:
    a list of `IAdaptable` that adapt to `View`.

### executeCommand

    protected void executeCommand(Command cmd)

  Executes the supplied command inside an `unchecked action`

  Parameters:
    `cmd` - command that can be executed (i.e., cmd.canExecute() == true)

### getCreateViewCommand

    protected Command getCreateViewCommand(CreateRequest request)

  Returns a `CreateCommand` for each view descriptor contained in the supplied request without forwarding create requests to the host editpart.

  Parameters:
    `request` - a create request
  Returns:
    command create view command(s)

### getCreateViewCommand

    protected ICommand getCreateViewCommand(CreateViewRequest.ViewDescriptor descriptor)

  Parameters:
    `descriptor` -
  Returns:
    ICommand to create a view given a descriptor

### getCreateViewRequest

    protected CreateViewRequest getCreateViewRequest(java.util.List descriptors)

  Return a create view request.

  Parameters:
    `descriptors` - a `CreateViewRequest.ViewDescriptor` list.
  Returns:
    a create request

### getViewDescriptor

    protected CreateViewRequest.ViewDescriptor getViewDescriptor(IAdaptable elementAdapter,
                                                                 java.lang.Class viewKind,
                                                                 java.lang.String hint,
                                                                 int index)

  Return a view descriptor.

  Parameters:
    `elementAdapter` - semantic element
    `viewKind` - type of view to create
    `hint` - factory hint
    `index` - index
  Returns:
    a create non-persisted view descriptor

### getViewDescriptor

    protected CreateViewRequest.ViewDescriptor getViewDescriptor(EObject element)

  Convenience method to create a view descriptor. Will call `CanonicalEditPolicy.getViewDescriptor(IAdaptable, Class, String, int)`

  Parameters:
    `element` - semantic element.
  Returns:
    view descriptor

### activate

    public void activate()

  Registers with the model server to receive semantic events targeted to the host editpart. By default, this editpolicy will receive events fired to the semantic element mapped to the host editpart. Clients wanting to listen to another semantic element should override `CanonicalEditPolicy.getSemanticHost()`

  Specified by:
    `activate` in interface `EditPolicy`
  See Also:
    `CanonicalEditPolicy.deactivate()`

### refreshOnActivate

    protected void refreshOnActivate()

  Refresh that is called on activate of the editpolicy to ensure that all relevant editparts can receive canonically created connections.

### isEnabled

    public boolean isEnabled()

  Return `true` if the editpolicy is enabled and its host is visible; otherwise `false`.

  Returns:
    `true`

### enableRefresh

    public void enableRefresh(boolean enable)

  Disables the editpolicy. While disabled, the editpolicy will not perform any refreshes.

  Parameters:
    `enable` -

### setEnable

    public void setEnable(boolean enable)

  Sets enable(aBoolean) on all the edit policies of the semantic host.

  Parameters:
    `enable` -

### isActive

    public final boolean isActive()

  check is this edit policy is active or not

  Returns:
    `true` if the this editpart has already been activated; otherwise `false`.

### getSemanticHost

    public EObject getSemanticHost()

  Return the semantic element to be listened to by this editpolicy.

  Returns:
    `host().getView().resolveSemanticElement()` by default.

### deactivate

    public void deactivate()

  Unregisters all registered model server listeners.

  Specified by:
    `deactivate` in interface `EditPolicy`
  See Also:
    `CanonicalEditPolicy.activate()`

### addListenerFilter

    protected boolean addListenerFilter(java.lang.String filterId,
                                        NotificationListener listener,
                                        EObject element)

  Adds a listener filter by adding the given listener to a passed notifier. The supplied `listener` will not be added to there is already a listener registered against the supplied `filterId`

  Parameters:
    `filterId` - A unique filter id (within the same editpart instance)
    `listener` - A listener instance
  Returns:
    `true` if the listener was added, otherwise `false`
  Throws:
    `java.lang.NullPointerException` - if either `filterId` or `listner` parameters are `null`.

### addListenerFilter

    protected boolean addListenerFilter(java.lang.String filterId,
                                        NotificationListener listener,
                                        EObject element,
                                        EStructuralFeature feature)

  Adds a listener filter by adding the given listener to a passed notifier. The supplied `listener` will not be added to there is already a listener registered against the supplied `filterId`

  Parameters:
    `filterId` - A unique filter id (within the same editpart instance)
    `listener` - A listener instance
  Returns:
    `true` if the listener was added, otherwise `false`
  Throws:
    `java.lang.NullPointerException` - if either `filterId` or `listner` parameters are `null`.

### removeListenerFilter

    protected void removeListenerFilter(java.lang.String filterId)

  Removes a listener previously added with the given id

  Parameters:
    `filterId` - the filter id

### notifyChanged

    public final void notifyChanged(Notification notification)

  Event callback: filters out non IElementEvent events.

  Specified by:
    `notifyChanged` in interface `NotificationListener`
  Parameters:
    `notification` - the notification object

### isHostStillValid

    protected final boolean isHostStillValid()

  Return `true` if the host is active and its view has not been deleted; otherwise `false`

  Returns:
    true or false

### handleNotificationEvent

    protected void handleNotificationEvent(Notification event)

  Handles `NotificationEvent` and resynchronizes the canonical container if the event should be handled.

  Parameters:
    `event` - `NotificationEvent` to handle.

### shouldHandleNotificationEvent

    protected boolean shouldHandleNotificationEvent(Notification event)

  Determines if the the `NotificationEvent` should be handled / processed by the editpolicy.

  Parameters:
    `event` - `NotificationEvent` to check
  Returns:
    `true` if event should be handled, `false` otherwise.

### getViewChildren

    protected java.util.List getViewChildren()

  Return the host's model children.

  Returns:
    list of `View`s

### refresh

    public final void refresh()

  Resynchronize the canonical container.

### refreshSemantic

    protected void refreshSemantic()

  Redirects the call to `CanonicalEditPolicy.refreshSemanticChildren()`.

### makeViewsMutable

    protected final void makeViewsMutable(java.util.List createdViews)

  Sets state on views to allow for modification without changing their non-persisted status.

  Parameters:
    `createdViews` - <code<>List of view adapters that were created during the `CanonicalEditPolicy.refreshSemantic()` operation

### makeViewsImmutable

    protected final void makeViewsImmutable(java.util.List createdViews)

  Sets views as being immutable, meaning that they are unmodifiable as non-persisted views. Any subsequent change to an immutable view will force the view to be persisted.

  Parameters:
    `createdViews` - <code<>List of view adapters that were created during the `CanonicalEditPolicy.refreshSemantic()` operation

### refreshSemanticChildren

    protected final java.util.List refreshSemanticChildren()

  Updates the set of children views so that it is in sync with the semantic children. This method is called in response to notification from the model.

  The update is performed by comparing the exising views with the set of semantic children returned from `CanonicalEditPolicy.getViewChildren()`. Views whose semantic element no longer exists are `removed`. New semantic children have their View `created`. Subclasses must override `getSemanticChildren()`.

  Unlike `AbstractEditPart#refreshChildren()`, this refresh will not reorder the view list to ensure both it and the semantic children are in the same order since it is possible that this edit policy will handle a specifc subset of the host's views.

  The host is refreshed if a view has created or deleted as a result of this refresh.

  Returns:
    `List` of new `View` objects that were created as a result of the synchronization

### cleanCanonicalSemanticChildren

    protected final java.util.List cleanCanonicalSemanticChildren(java.util.Collection viewChildren,
                                                                  java.util.Collection semanticChildren)

  Synchronizes the semanticChildren the viewChildren to discover if any of the semanticChildren don't have a corresponding view. Any `semanticChildren` that do have a view are removed from the list.

  Parameters:
    `viewChildren` - `List` of `View` elements that already exist in the container.
    `semanticChildren` - `List` of semantic elements that are candidates for synchronization
  Returns:
    `List` of orphans views that should be deleted from the container.

### postProcessRefreshSemantic

    protected void postProcessRefreshSemantic(java.util.List viewDescriptors)

  Allow for post processing of the refresh semantic to set the view mutable state and allow subclasses to add functionality.

  Parameters:
    `viewDescriptors` - `List` of IAdaptable that adapt to `View`

### resolveSemanticElement

    protected final EObject resolveSemanticElement()

  Convenience method to return the host's semantic element. Same as calling `host().getView().resolveSemanticElement();`

  Returns:
    an `EObject`

### getCanonicalStyle

    protected CanonicalStyle getCanonicalStyle()

  gets the canonical style that may be installed on the host shape compartment view.

  Returns:
    `CanonicalStyle`

### getViewer

    public final EditPartViewer getViewer()

Runtime

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp., Borland Software Corp., and others 2005,2006. All rights reserved.