bundles/org.simantics.project/src/org/simantics/project/IProject.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;\r
  13 \r
  14 import org.simantics.db.Resource;\r
  15 import org.simantics.db.Session;\r
  16 import org.simantics.project.exception.ProjectException;\r
  17 import org.simantics.project.features.IProjectFeature;\r
  18 import org.simantics.utils.Container;\r
  19 import org.simantics.utils.datastructures.disposable.IDisposable;\r
  20 import org.simantics.utils.datastructures.hints.IHintContext;\r
  21 \r
  22 /**\r
  23  * <ul>\r
  24  * <li>A project is always related to a single database session.</li>\r
  25  * <li>Disposing an IProject shall release all temporarily allocated resources, but it shall not remove anything that will prevent the project from being reloaded</li>\r
  26  * <li>Features only configure/deconfigure this IProject by adding/removing things from the IHintContext</li>\r
  27  * <li>A feature should only perform a single task</li>\r
  28  * <li>Features should be easily composable into new features</li>\r
  29  * <li>Life-cycle handlers that perform project-specific (de)initialization tasks, can be added to projects</li>\r
  30  * </ul>\r
  31  * \r
  32  * @author Tuukka Lehtonen\r
  33  */\r
  34 public interface IProject extends IDisposable, IHintContext, Container<Resource> {\r
  35 \r
  36     /**\r
  37      * @return the session this project is related to.\r
  38      */\r
  39     Session getSession();\r
  40 \r
  41     /**\r
  42      * @return the features used with this <code>IProject</code>. Depending on\r
  43      *         whether the the project is activated or not, the features will be\r
  44      *         either configured or unconfigured.\r
  45      * @see #activate()\r
  46      * @see #deactivate()\r
  47      */\r
  48     IProjectFeature[] getFeatures();\r
  49 \r
  50     /**\r
  51      * Activates the project.\r
  52      * \r
  53      * <p>\r
  54      * This implies invoking all {@link IProjectFeature#configure()} handlers\r
  55      * that are attached to this project. The invocation order is the same as in\r
  56      * which {@link #getFeatures()} returns the features. If the project has\r
  57      * already been activated, this should be a null operation.\r
  58      * </p>\r
  59      * <p>\r
  60      * This method may only be invoked outside of any transaction. This allows\r
  61      * the {@link IProjectFeature} handlers to perform arbitrary read and/or\r
  62      * write requests into the database.\r
  63      * </p>\r
  64      */\r
  65     void activate() throws ProjectException;\r
  66 \r
  67     /**\r
  68      * Deactivates the project.\r
  69      * \r
  70      * <p>\r
  71      * A deactivated project can be activated again later, as long as it isn't\r
  72      * disposed.\r
  73      * </p>\r
  74      * \r
  75      * <p>\r
  76      * This implies invoking all {@link IProjectFeature#deconfigure()} handlers\r
  77      * that are attached to this project. The invocation order is the reverse of\r
  78      * the activation order. If the project is already inactive, this should be\r
  79      * a null operation.\r
  80      * </p>\r
  81      * \r
  82      * <p>\r
  83      * Project disposal also implies deactivation.\r
  84      * </p>\r
  85      */\r
  86     void deactivate() throws ProjectException;\r
  87 \r
  88 }\r