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 }