001: /*******************************************************************************
002: * Copyright (c) 2000, 2005 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.activities;
011:
012: import java.util.Set;
013:
014: /**
015: * An instance of this interface is an activity as defined by the extension
016: * point <code>org.eclipse.ui.activities</code>.
017: *
018: * <p>
019: * An instance of this interface can be obtained from an instance of
020: * <code>IActivityManager</code> for any identifier, whether or not an activity
021: * with that identifier is defined in the extension registry.
022: * </p>
023: *
024: * <p>
025: * The handle-based nature of this API allows it to work well with runtime
026: * plugin activation and deactivation, which can cause dynamic changes to the
027: * extension registry. A client may get an <code>IActivity</code> handle that
028: * is currently undefined ({@link #isDefined()} equals <code>false</code>) and
029: * listen for it to become defined.
030: * </p>
031: *
032: * <p>
033: * This interface is not intended to be extended or implemented by clients.
034: * </p>
035: *
036: * @since 3.0
037: * @see IActivityManager
038: */
039: public interface IActivity extends Comparable {
040:
041: /**
042: * Registers an instance of <code>IActivityListener</code> to listen for
043: * changes to properties of this instance.
044: *
045: * @param activityListener
046: * the instance to register. Must not be <code>null</code>.
047: * If an attempt is made to register an instance which is
048: * already registered with this instance, no operation is
049: * performed.
050: */
051: void addActivityListener(IActivityListener activityListener);
052:
053: /**
054: * Returns the set of activity requirement bindings for this instance.
055: * <p>
056: * This method will return all activity requirement bindings for this
057: * instance, whether or not this instance is defined.
058: * </p>
059: * <p>
060: * Notification is sent to all registered listeners if this property
061: * changes.
062: * </p>
063: *
064: * @return the set of activity requirement bindings. This set may be empty,
065: * but is guaranteed not to be <code>null</code>. If this set is
066: * not empty, it is guaranteed to only contain instances of
067: * <code>IActivityRequirementBinding</code>.
068: * @see IActivityRequirementBinding
069: */
070: Set getActivityRequirementBindings();
071:
072: /**
073: * Returns the set of activity pattern bindings for this instance.
074: * <p>
075: * This method will return all activity pattern bindings for this instance,
076: * whether or not this instance is defined.
077: * </p>
078: * <p>
079: * Notification is sent to all registered listeners if this property
080: * changes.
081: * </p>
082: *
083: * @return the set of activity pattern bindings. This set may be empty, but
084: * is guaranteed not to be <code>null</code>. If this set is not
085: * empty, it is guaranteed to only contain instances of <code>IActivityPatternBinding</code>.
086: * @see IActivityPatternBinding
087: */
088: Set getActivityPatternBindings();
089:
090: /**
091: * Returns the identifier of this instance.
092: *
093: * @return the identifier of this instance. Guaranteed not to be <code>null</code>.
094: */
095: String getId();
096:
097: /**
098: * Returns the name of this instance suitable for display to the user.
099: * <p>
100: * Notification is sent to all registered listeners if this property
101: * changes.
102: * </p>
103: *
104: * @return the name of this instance. Guaranteed not to be <code>null</code>.
105: * @throws NotDefinedException
106: * if this instance is not defined.
107: */
108: String getName() throws NotDefinedException;
109:
110: /**
111: * Returns the description of this instance suitable for display to the user.
112: * <p>
113: * Notification is sent to all registered listeners if this property
114: * changes.
115: * </p>
116: *
117: * @return the description of this instance. Guaranteed not to be <code>null</code>.
118: * @throws NotDefinedException
119: * if this instance is not defined.
120: */
121: String getDescription() throws NotDefinedException;
122:
123: /**
124: * Returns whether or not this instance is defined. A defined activity
125: * may have a name, description and bindings (both pattern and relational).
126: * <p>
127: * Notification is sent to all registered listeners if this property
128: * changes.
129: * </p>
130: *
131: * @return <code>true</code>, iff this instance is defined.
132: */
133: boolean isDefined();
134:
135: /**
136: * Returns whether or not this instance is enabled.
137: * <p>
138: * Notification is sent to all registered listeners if this property
139: * changes.
140: * </p>
141: *
142: * @return <code>true</code>, iff this instance is enabled.
143: */
144: boolean isEnabled();
145:
146: /**
147: * Returns whether or not this instance should be enabled by default.
148: *
149: * @return <code>true</code>, iff this instance should be enabled by default.
150: * @throws NotDefinedException
151: * if this instance is not defined.
152: * @since 3.1
153: */
154: boolean isDefaultEnabled() throws NotDefinedException;
155:
156: /**
157: * Removes an instance of <code>IActivityListener</code> listening
158: * for changes to properties of this instance.
159: *
160: * @param activityListener
161: * the instance to remove. Must not be <code>null</code>.
162: * If an attempt is made to remove an instance which is not
163: * already registered with this instance, no operation is
164: * performed.
165: */
166: void removeActivityListener(IActivityListener activityListener);
167: }
|