|
|
| Line 1: |
Line 1: |
| | '''org.simantics.project''' ([[svn:foundation/project/trunk/org.simantics.project|SVN]]) is a run-time framework for accessing and manipulating projects in Simantics. It works on top of the graph database API, [[org.simantics.db]]. | | '''org.simantics.project''' ([[svn:foundation/project/trunk/org.simantics.project|SVN]]) is a run-time framework for accessing and manipulating projects in Simantics. It works on top of the graph database API, [[org.simantics.db]]. |
| − |
| |
| − | = Overview =
| |
| − |
| |
| − | In Simantics, a semantic database is conceptually broken into ''projects'' and ''configuration''. A database can contain any number of projects but there is a single configuration area that contains settings global for all projects.
| |
| − |
| |
| − | The database uses the following structure:
| |
| − | : <code>Root Library : L0.Library (=http:/)</code>
| |
| − | ::* A common entry point that always exists (see Builtins.URIs.RootLibrary)
| |
| − | :: <code>Consists Of</code>
| |
| − | ::: <code>Projects : L0.Library (=http://Projects)</code>
| |
| − | ::::* Consists of all projects contained by the database
| |
| − | ::: <code>InstalledGraphBundles : L0.Entity (=http://InstalledGraphBundles)</code>
| |
| − | ::::* Consists of the ontology bundles (.tg files) imported into this database. See [[svn:foundation/ontologies/trunk/org.simantics.layer0/graph/DatabaseManagement.pgraph|DatabaseManagement.pgraph]] for the related ontology.
| |
| − |
| |
| − | [[File:projects.png|center|frame|480px|The conceptual foundation of the project framework. ([[File:projects.graphml|image source]])]]
| |
| − |
| |
| − | The project system of Simantics is based on features. A feature in this context is simply an abstract means for configuring an [[svn:foundation/branches/dev6/org.simantics.project/src/org/simantics/project/IProject.java|IProject]] object. An ''IProject'' is an ''IHintContext''. The hint context aspect of IProject is used for runtime storage of all project-related attributes, such as the currently selected model or services that can be used to perform project-type specific actions on the project in an abstract fashion. Implementing IHintContext allows for other parties to listen to changes in project attributes.
| |
| − |
| |
| − | Project features can ''depend on'' (''require'') other features. This information is used to construct the order in which features configure/deconfigure a project, which is resolved through [[wikipedia:Topological_sorting|topological sorting]].
| |
| − |
| |
| − | = Creating a new project type =
| |
| − |
| |
| − | == (Optional) Step 1: model your project features ==
| |
| − |
| |
| − | This step is not absolutely necessary but recommended nevertheless. This example only shows how to make a project type advertise ontology dependencies of projects which is necessary for example if dependency indexing is desired.
| |
| − |
| |
| − | Following the instructions at [[org.simantics.graph]] create a project to contain Simantics ontologies and add a new <code>.pgraph</code> file into it. You can fill the .pgraph with something like the following:
| |
| − |
| |
| − | <blockquote>
| |
| − | <source lang="python">
| |
| − | L0 = <http://www.simantics.org/Layer0-1.0>
| |
| − | PROJ = <http://www.simantics.org/Project-1.0>
| |
| − |
| |
| − | MY_ONTOLOGY = <http://www.example.org/MyOntology-1.0> : L0.Ontology
| |
| − | @L0.new
| |
| − |
| |
| − | MY_ONTOLOGY.ImportedOntologies : PROJ.NamespaceRequirement
| |
| − | L0.HasDescription "Specifies the ontologies required by a this project. Used e.g. for indexing the database."
| |
| − | PROJ.RequiresNamespace
| |
| − | "http://www.simantics.org/G2D-1.0" : L0.URI
| |
| − | "http://www.simantics.org/Diagram-2.0" : L0.URI
| |
| − | </source>
| |
| − | </blockquote>
| |
| − |
| |
| − | == Step 2: define extensions for your project features ==
| |
| − |
| |
| − | Extensions are defined using the <code>org.simantics.project.feature</code> extension point. See the extensions point's own reference document for detailed information (currently only viewable by opening the EP in eclipse).
| |
| − |
| |
| − | The following example demonstrates the use of all current features of the extension point, namely project features, dependencies between project features and bindings between project features and platform features. This example assumes that you have a plug-in <code>myplugin</code> and a feature project <code>myplugin.feature (feature id=myplugin)</code> for it.
| |
| − |
| |
| − | <blockquote>
| |
| − | <source lang="xml">
| |
| − | <extension
| |
| − | point="org.simantics.project.feature">
| |
| − | <feature
| |
| − | description="My project type's main project feature."
| |
| − | class="myplugin.MyProjectFeature"
| |
| − | id="myplugin.project"
| |
| − | label="My project"
| |
| − | published="true">
| |
| − | <requires id="myplugin.dependencies"/>
| |
| − | <installGroup id="myplugin.feature.group"/>
| |
| − | </feature>
| |
| − | <feature
| |
| − | class="org.simantics.project.features.DependencyValidationFeature:http://www.example.org/MyOntology-1.0/ImportedOntologies"
| |
| − | id="myplugin.dependencies"
| |
| − | label="My plugin dependencies">
| |
| − | </feature>
| |
| − | </extension>
| |
| − | </source>
| |
| − | </blockquote>
| |
| − |
| |
| − | == Step 3: define the code for the project features ==
| |
| − |
| |
| − | * Add dependency on plug-in org.simantics.project.
| |
| − | * Copy the following classes into corresponding source files:
| |
| − | <blockquote>
| |
| − | <source lang="java">
| |
| − | package myplugin;
| |
| − | class MyProjectFeature extends AbstractProjectFeature {
| |
| − |
| |
| − | private static final String DEFAULT_PERSPECTIVE = "myplugin.myperspective";
| |
| − |
| |
| − | @Override
| |
| − | public void configure() throws ProjectException {
| |
| − | Collection<String> perspectives = new ArrayList<String>();
| |
| − | perspectives.add(DEFAULT_PERSPECTIVE);
| |
| − |
| |
| − | getProject().setHint(ProjectKeys.DEFAULT_PERSPECTIVE, DEFAULT_PERSPECTIVE);
| |
| − | getProject().setHint(ProjectKeys.PERSPECTIVES, perspectives);
| |
| − | }
| |
| − |
| |
| − | @Override
| |
| − | public void deconfigure() throws ProjectException {
| |
| − | // Dispose of anything that needs to be disposed of within the project's
| |
| − | // hint context which can be accessed through getProjectElement().
| |
| − | }
| |
| − | }
| |
| − | </source>
| |
| − |
| |
| − |
| |
| − | <source lang="java">
| |
| − | package myplugin;
| |
| − | class MyDummyFeature extends AbstractProjectFeature {
| |
| − |
| |
| − | @Override
| |
| − | public void configure() throws ProjectException {
| |
| − | // Setup some hints if you need to
| |
| − | // Do something with the database
| |
| − | getSession().syncRequest(new WriteRequest() {
| |
| − | @Override
| |
| − | public void perform(WriteGraph graph) throws DatabaseException {
| |
| − | //...
| |
| − | }
| |
| − | });
| |
| − | }
| |
| − |
| |
| − | @Override
| |
| − | public void deconfigure() throws ProjectException {
| |
| − | // Dispose of anything that needs to be disposed of within the project's
| |
| − | // hint context which can be accessed through getProjectElement().
| |
| − | }
| |
| − | }
| |
| − | </source>
| |
| − | </blockquote>
| |
| − |
| |
| − | = Development =
| |
| − |
| |
| − | == Interfaces ==
| |
| − |
| |
| − | [[File:project-api.png|center|frame|480px|Project framework API and internals. ([[File:project-api.graphml|image source]])]]
| |
| − |
| |
| − | == Scenarios ==
| |
| − |
| |
| − | === Load project from database and activate it ===
| |
| − |
| |
| − | <source lang="java">
| |
| − | public IProject loadAndActivateProject(Session session, Resource project) throws DatabaseException, ProjectException {
| |
| − | IProject project = Projects.loadProject(session, project);
| |
| − | project.activate();
| |
| − | return project;
| |
| − | }
| |
| − | </source>
| |
| − |
| |
| − | === Retrieving the active project ===
| |
| − |
| |
| − | The Simantics Workbench UI is built so that always when the user is working on a project, the UI will have both '''an active database session''' and '''an active project'''. The active project can be used to store any project-related services and data using the IHintContext interface it implements.
| |
| − |
| |
| − | <code>SimanticsUI</code> ([[svn:foundation/trunk/org.simantics.ui/src/org/simantics/ui/SimanticsUI.java|SVN]]) is the class for retrieving both ''the active database session'' and ''the active project'' using these:
| |
| − |
| |
| − | <source lang="java">
| |
| − | public class SimanticsUI {
| |
| − | ...
| |
| − |
| |
| − | /**
| |
| − | * Returns the database session context associated with the currently active
| |
| − | * workbench window. This method should be used to retrieve session contexts
| |
| − | * only when the client is sure that the correct workbench window has focus.
| |
| − | *
| |
| − | * <p>
| |
| − | * If the client knows the workbench window it is working with, but it isn't
| |
| − | * sure that the correct workbench window has focus, use
| |
| − | * {@link #getSessionContext(Object)} instead.
| |
| − | * </p>
| |
| − | *
| |
| − | * @return the session context associated with the currently active
| |
| − | * workbench window or <code>null</code> if the active window has no
| |
| − | * session context
| |
| − | */
| |
| − | public static ISessionContext getSessionContext() { ... }
| |
| − |
| |
| − | /**
| |
| − | * @return the currently open and active project as an IProject or
| |
| − | * <code>null</code> if there is no active session or project
| |
| − | */
| |
| − | public static IProject peekProject() { ... }
| |
| − |
| |
| − | /**
| |
| − | * @return the currently open and active project as an IProject
| |
| − | * @throws IllegalStateException if there is no currently active database
| |
| − | * session, which also means there is no active project at the
| |
| − | * moment
| |
| − | */
| |
| − | public static IProject getProject() { ... }
| |
| − |
| |
| − | ...
| |
| − | }
| |
| − | </source>
| |
| | | | |
| | = Download = | | = Download = |
