bundles/org.simantics.project/src/org/simantics/project/features/IProjectFeature.java

   1 /*******************************************************************************\r
   2  * Copyright (c) 2007, 2010 Association for Decentralized Information Management\r
   3  * in Industry THTH ry.\r
   4  * All rights reserved. This program and the accompanying materials\r
   5  * are made available under the terms of the Eclipse Public License v1.0\r
   6  * which accompanies this distribution, and is available at\r
   7  * http://www.eclipse.org/legal/epl-v10.html\r
   8  *\r
   9  * Contributors:\r
  10  *     VTT Technical Research Centre of Finland - initial API and implementation\r
  11  *******************************************************************************/\r
  12 package org.simantics.project.features;
  13
  14 import org.simantics.project.IProject;\r
  15 import org.simantics.project.exception.ProjectException;\r
  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 {\r
  41     /**\r
  42      * Configures this feature for its project. This is called during\r
  43      * {@link IProject#activate()} and should not be called directly by clients.\r
  44      * \r
  45      * <p>\r
  46      * Exceptions thrown by this method will be propagated back to the caller of\r
  47      * <code>IProject.activate</code>.\r
  48      * \r
  49      * @exception ProjectException if this method fails.\r
  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;\r
  66 \r
  67     /**\r
  68      * Returns the project to which this project feature applies. This method\r
  69      * may only be invoked from within {@link #configure()} and\r
  70      * {@link #deconfigure()}. At other times it is not guaranteed to return the\r
  71      * project.\r
  72      * \r
  73      * @return the project handle\r
  74      */
  75     IProject getProjectElement();\r
  76 \r
  77     /**\r
  78      * Sets the project to which this feature applies. This method should not be\r
  79      * called directly by clients. It is only to be used internally by\r
  80      * {@link IProject#activate()} during project activation and more precisely\r
  81      * project feature configuration.\r
  82      * \r
  83      * @param project the project to which this feature applies\r
  84      */
  85     void setProjectElement(IProject project);\r
  86
  87 }