]> gerrit.simantics Code Review - simantics/platform.git/blob - bundles/org.simantics.project/src/org/simantics/project/features/IProjectFeature.java
Support for multiple installable TG files in single bundle
[simantics/platform.git] / bundles / org.simantics.project / src / org / simantics / project / features / IProjectFeature.java
1 /*******************************************************************************
2  * Copyright (c) 2007, 2010 Association for Decentralized Information Management
3  * in Industry THTH ry.
4  * All rights reserved. This program and the accompanying materials
5  * are made available under the terms of the Eclipse Public License v1.0
6  * which accompanies this distribution, and is available at
7  * http://www.eclipse.org/legal/epl-v10.html
8  *
9  * Contributors:
10  *     VTT Technical Research Centre of Finland - initial API and implementation
11  *******************************************************************************/
12 package org.simantics.project.features;
13
14 import org.simantics.project.IProject;
15 import org.simantics.project.exception.ProjectException;
16
17 /**
18  * Interface for project feature runtime classes. It can configure a project
19  * with the project feature, or de-configure it. When a project is configured
20  * with a project feature, this is recorded in the list of project features on
21  * the project. Individual project features may expose a more specific runtime
22  * type, with additional API for manipulating the project in a feature-specific
23  * way.
24  * 
25  * <p>
26  * NOTE: Project features are stateful objects bound to a single
27  * <code>IProject</code> (e.g. <code>IProject</code>) at a time. Do not
28  * cache or re-use project features.
29  * </p>
30  * 
31  * <p>
32  * Clients may implement this interface but extending
33  * <code>AbstractProjectFeature</code> is strongly recommended instead.
34  * </p>
35  * 
36  * @see IProject#getFeatures()
37  * @see AbstractProjectFeature
38  * @see IProjectFeatureDescriptor
39  */
40 public interface IProjectFeature {
41     /**
42      * Configures this feature for its project. This is called during
43      * {@link IProject#activate()} and should not be called directly by clients.
44      * 
45      * <p>
46      * Exceptions thrown by this method will be propagated back to the caller of
47      * <code>IProject.activate</code>.
48      * 
49      * @exception ProjectException if this method fails.
50      */
51     void configure() throws ProjectException;
52
53     /**
54      * De-configures this feature for its project. This is called by the
55      * workspace when features are removed from the project using
56      * <code>IProject.setDescription</code> and should not be called directly by
57      * clients. The feature extension id is removed from the list of features
58      * before this method is called, and need not be removed here.
59      * 
60      * Exceptions thrown by this method will be propagated back to the caller of
61      * <code>IProject.deactivate</code>.
62      * 
63      * @exception ProjectException if this method fails.
64      */
65     void deconfigure() throws ProjectException;
66
67     /**
68      * Returns the project to which this project feature applies. This method
69      * may only be invoked from within {@link #configure()} and
70      * {@link #deconfigure()}. At other times it is not guaranteed to return the
71      * project.
72      * 
73      * @return the project handle
74      */
75     IProject getProjectElement();
76
77     /**
78      * Sets the project to which this feature applies. This method should not be
79      * called directly by clients. It is only to be used internally by
80      * {@link IProject#activate()} during project activation and more precisely
81      * project feature configuration.
82      * 
83      * @param project the project to which this feature applies
84      */
85     void setProjectElement(IProject project);
86
87 }