ICategory


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  
12  package org.eclipse.ui.activities;
13  
14  import java.util.Set  ;
15  
16  /**
17   * An instance of this interface is a category as defined by the extension
18   * point <code>org.eclipse.ui.activities</code>.
19   * <p>
20   * An instance of this interface can be obtained from an instance of 
21   * <code>IActivityManager</code> for any identifier, whether or not a category 
22   * with that identifier is defined in the extension registry.
23   * </p>
24   * <p>
25   * The handle-based nature of this API allows it to work well with runtime
26   * plugin activation and deactivation, which can cause dynamic changes to the
27   * extension registry.
28   * </p>
29   * <p>
30   * This interface is not intended to be extended or implemented by clients.
31   * </p>
32   * 
33   * @since 3.0
34   * @see IActivityManager
35   */
36  public interface ICategory extends Comparable   {
37  
38      /**
39       * Registers an instance of <code>ICategoryListener</code> to listen for
40       * changes to properties of this instance.
41       * 
42       * @param categoryListener
43       *            the instance to register. Must not be <code>null</code>.
44       *            If an attempt is made to register an instance which is
45       *            already registered with this instance, no operation is
46       *            performed.
47       */
48      void addCategoryListener(ICategoryListener categoryListener);
49  
50      /**
51       * Returns the set of category activity bindings for this instance.
52       * <p>
53       * This method will return all category activity bindings for this
54       * instance, whether or not this instance is defined.
55       * </p>
56       * <p>
57       * Notification is sent to all registered listeners if this property
58       * changes.
59       * </p>
60       * 
61       * @return the set of category activity bindings. This set may be empty,
62       *         but is guaranteed not to be <code>null</code>. If this set is
63       *         not empty, it is guaranteed to only contain instances of <code>ICategoryActivityBinding</code>.
64       * @see ICategoryActivityBinding
65       */
66      Set   getCategoryActivityBindings();
67  
68      /**
69       * Returns the identifier of this instance.
70       * 
71       * @return the identifier of this instance. Guaranteed not to be <code>null</code>.
72       */
73      String   getId();
74  
75      /**
76       * Returns the name of this instance suitable for display to the user.
77       * <p>
78       * Notification is sent to all registered listeners if this property
79       * changes.
80       * </p>
81       * 
82       * @return the name of this instance. Guaranteed not to be <code>null</code>.
83       * @throws NotDefinedException
84       *             if this instance is not defined.
85       */
86      String   getName() throws NotDefinedException;
87  
88      /**
89       * Returns the description of this instance suitable for display to the user.
90       * <p>
91       * Notification is sent to all registered listeners if this property
92       * changes.
93       * </p>
94       * 
95       * @return the description of this instance. Guaranteed not to be <code>null</code>.
96       * @throws NotDefinedException
97       *             if this instance is not defined.
98       */
99      String   getDescription() throws NotDefinedException;
100 
101     /**
102      * Returns whether or not this instance is defined.
103      * <p>
104      * Notification is sent to all registered listeners if this property
105      * changes.
106      * </p>
107      * 
108      * @return <code>true</code>, iff this instance is defined.
109      */
110     boolean isDefined();
111 
112     /**
113      * Removes an instance of <code>ICategoryListener</code> listening
114      * for changes to properties of this instance.
115      * 
116      * @param categoryListener
117      *            the instance to remove. Must not be <code>null</code>.
118      *            If an attempt is made to remove an instance which is not
119      *            already registered with this instance, no operation is
120      *            performed.
121      */
122     void removeCategoryListener(ICategoryListener categoryListener);
123 }
124
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags