X-Git-Url: https://gerrit.simantics.org/r/gitweb?a=blobdiff_plain;f=bundles%2Forg.simantics.db.layer0%2Fsrc%2Forg%2Fsimantics%2Fdb%2Flayer0%2Fvariable%2FVariable.java;h=faa98369a00628ecbccc72be78d9d68b8bfa18d4;hb=035118aa5f35c9e5acd1f34d22065055dfdee486;hp=82a6ea5a61f5d486a50abbfc99af79e4fff21729;hpb=969bd23cab98a79ca9101af33334000879fb60c5;p=simantics%2Fplatform.git diff --git a/bundles/org.simantics.db.layer0/src/org/simantics/db/layer0/variable/Variable.java b/bundles/org.simantics.db.layer0/src/org/simantics/db/layer0/variable/Variable.java index 82a6ea5a6..faa98369a 100644 --- a/bundles/org.simantics.db.layer0/src/org/simantics/db/layer0/variable/Variable.java +++ b/bundles/org.simantics.db.layer0/src/org/simantics/db/layer0/variable/Variable.java @@ -1,298 +1,298 @@ -/******************************************************************************* - * Copyright (c) 2007, 2010 Association for Decentralized Information Management - * in Industry THTH ry. - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v1.0 - * which accompanies this distribution, and is available at - * http://www.eclipse.org/legal/epl-v10.html - * - * Contributors: - * VTT Technical Research Centre of Finland - initial API and implementation - *******************************************************************************/ -package org.simantics.db.layer0.variable; - -import java.util.Collection; -import java.util.Set; - -import org.simantics.databoard.binding.Binding; -import org.simantics.databoard.binding.mutable.Variant; -import org.simantics.databoard.type.Datatype; -import org.simantics.db.ReadGraph; -import org.simantics.db.Resource; -import org.simantics.db.WriteGraph; -import org.simantics.db.exception.DatabaseException; -import org.simantics.db.layer0.exception.NonWritableVariableException; -import org.simantics.db.layer0.request.PropertyInfo; -import org.simantics.db.layer0.variable.RVI.RVIPart; -import org.simantics.db.layer0.variable.Variables.Role; - -/* - * Variable is a standard i/o data interface to a model in Simantics. The variable interface provides - * - * - Unified data addressing in string format (URI) - * - Flattening of reusable component hierarchies - * - Runtime values - * - Derived values - * - * The Variable interface spans a tree of variables such that each node can have children and properties. - * - children are denoted by the '/' separator - * - properties are denoted by the '#' separator - * - * There are three kinds of URIs - * - * Variable URI: - * A standard random access identifier to a variable. - * Examples: - * - http://www.asd.org/Projects/AprosModel1/BaseRealization/Diagram/PI_X#PI_MASS_FLOW - * - http://www.asd.org/Projects/AprosModel1/Experiment/UUID/Diagram/PI_X#PI_MASS_FLOW#Unit - * Realization URI: - * A random access identifier to a context under which a valuation of a model is presented. - * A realization URI is guaranteed to have a unique resource obtainable by ReadGraph.getResource() - * Examples: - * - http://www.asd.org/Projects/AprosModel1/BaseRealization - * - http://www.asd.org/Projects/AprosModel1/Experiment/UUID - * Relative Variable Identifier (RVI): - * A reference which can be used to obtain a variable when realization is given - * Examples: - * - /Diagram/PI_X#PI_MASS_FLOW - * - /Diagram/PI_X#PI_MASS_FLOW#Unit - * - * Use cases: - * - * 1. Given a configuration resource and context variable obtain variable - * Procedure: call Variable.browse(ReadGraph, Resource) - * - * 2. Given two variables obtain RVI of second based on first - * Procedure: call Variables.getRVI(Variable, Variable) - * - * 3. Given Realization URI obtain Variable - * Procedure: call ReadGraph.getResource and then adapt(Resource, Variable.class) - * - * 4. Given Realization URI and RVI, obtain Variable - * Procedure: obtain Variable from Realization URI, call Variable.browse(ReadGraph, String) - * - * 5. Given Variable URI, obtain Variable - * Procedure: call Variables.getVariable(ReadGraph, String) - * - * 6. Given Variable, obtain model - * Procedure: call Variables.getModel(ReadGraph, Variable) - * - * 7. Given Variable, obtain realization - * Procedure: call Variables.getRealization(ReadGraph, Variable) - - * 8. Given Variable, obtain Variable in other realization - * Procedure: call Variables.switchRealization(ReadGraph, Variable, Resource) - * - */ - - -public interface Variable { - - /* - * Convenience method for getting the value of a named property. - */ - T getPropertyValue(ReadGraph graph, String name) throws DatabaseException; - T getPropertyValue(ReadGraph graph, Resource property) throws DatabaseException; - T getPossiblePropertyValue(ReadGraph graph, String name) throws DatabaseException; - T getPossiblePropertyValue(ReadGraph graph, Resource property) throws DatabaseException; - /* - * Convenience method for getting the value of a named property. - */ - T getPropertyValue(ReadGraph graph, String name, Binding binding) throws DatabaseException; - T getPropertyValue(ReadGraph graph, Resource property, Binding binding) throws DatabaseException; - T getPossiblePropertyValue(ReadGraph graph, String name, Binding binding) throws DatabaseException; - T getPossiblePropertyValue(ReadGraph graph, Resource property, Binding binding) throws DatabaseException; - /* - * Gets the value of the property. Binding is default. - */ - T getValue(ReadGraph graph) throws DatabaseException; - T getPossibleValue(ReadGraph graph) throws DatabaseException; - /* - * Gets the value of the property. Binding is explicitly given. - */ - T getValue(ReadGraph graph, Binding binding) throws DatabaseException; - T getPossibleValue(ReadGraph graph, Binding binding) throws DatabaseException; - Variant getVariantValue(ReadGraph graph) throws DatabaseException; - - /* - * If role is Property returns the corresponding PropertyInfo. - * @throws DatabaseException if role of this variable is not Property - */ - PropertyInfo getPropertyInfo(ReadGraph graph) throws DatabaseException; - - /** - * @return the index root resource or null if the index root - * cannot be found - * @throws DatabaseException in any other error conditions - */ - Resource getIndexRoot(ReadGraph graph) throws DatabaseException; - - /** - * Writes a value using the given binding. - * - * @throws NonWritableVariableException if the variable is not writable - * @throws DatabaseException in any other error conditions - */ - void setValue(WriteGraph graph, Object value, Binding binding) throws DatabaseException; - /** - * Writes a value with default binding based on the value class. - * - * @throws NonWritableVariableException if the variable is not writable - * @throws DatabaseException in any other error conditions - */ - void setValue(WriteGraph graph, Object value) throws DatabaseException; - - /** - * Writes a value to the given property using the given binding. - * - * @throws NonWritableVariableException if the variable is not writable - * @throws DatabaseException in any other error conditions - */ - void setPropertyValue(WriteGraph graph, String name, Object value, Binding binding) throws DatabaseException; - void setPropertyValue(WriteGraph graph, Resource property, Object value, Binding binding) throws DatabaseException; - /** - * Writes a value to the given property using the default binding based on - * the value class. - * - * @throws NonWritableVariableException if the variable is not writable - * @throws DatabaseException in any other error conditions - */ - void setPropertyValue(WriteGraph graph, String name, Object value) throws DatabaseException; - void setPropertyValue(WriteGraph graph, Resource property, Object value) throws DatabaseException; - - // TODO methods? - - /* - * Gets a named child of this variable. A child corresponds to a '/' in URI notation - */ - Variable getChild(ReadGraph graph, String name) throws DatabaseException; - Variable getPossibleChild(ReadGraph graph, String name) throws DatabaseException; - /* - * Gets a named property of this variable. A property corresponds to a '#' in URI notation - */ - Variable getProperty(ReadGraph graph, String name) throws DatabaseException; - Variable getProperty(ReadGraph graph, Resource property) throws DatabaseException; - Variable getPossibleProperty(ReadGraph graph, String name) throws DatabaseException; - Variable getPossibleProperty(ReadGraph graph, Resource property) throws DatabaseException; - - /* - * Browses all children of this variable. - * @deprecated replaced by {@link #getChildren(ReadGraph)} - */ - @Deprecated - Collection browseChildren(ReadGraph graph) throws DatabaseException; - - /* - * Gets all children of this variable. - */ - Collection getChildren(ReadGraph graph) throws DatabaseException; - - /* - * Browses all available properties of this variable. An empty collection shall - * be returned if there are no properties for this variable. - * @deprecated replaced by {@link #getProperties(ReadGraph)} - */ - @Deprecated - Collection browseProperties(ReadGraph graph) throws DatabaseException; - - /* - * Gets all available properties of this variable. An empty collection shall - * be returned if there are no properties for this variable. - */ - Collection getProperties(ReadGraph graph) throws DatabaseException; - /* - * Gets all properties of this variable such that {@link #getClassifications()} - * contains classification. An empty collection shall - * be returned if there are no properties for this variable. - */ - Collection getProperties(ReadGraph graph, String classification) throws DatabaseException; - Collection getProperties(ReadGraph graph, Resource classification) throws DatabaseException; - - /* - * Browses a single variable using the given suffix path. The suffix can contain various '/' and '#'. - */ - Variable browse(ReadGraph graph, String suffix) throws DatabaseException; - Variable browsePossible(ReadGraph graph, String suffix) throws DatabaseException; - - /* - * Browses a single variable using the given configuration resource. - */ - Variable browse(ReadGraph graph, Resource config) throws DatabaseException; - Variable browsePossible(ReadGraph graph, Resource config) throws DatabaseException; - - Variable resolve(ReadGraph graph, RVIPart part) throws DatabaseException; - Variable resolvePossible(ReadGraph graph, RVIPart part) throws DatabaseException; - - /* - * Gets the requested interface associated to this variable if available. - * Examples: - * -Resource - * -Accessor - * -Binding - * - */ - @Deprecated - T getInterface(ReadGraph graph, Class clazz) throws DatabaseException; - - T adapt(ReadGraph graph, Class clazz) throws DatabaseException; - T adaptPossible(ReadGraph graph, Class clazz) throws DatabaseException; - - /* - * Gets the unique URI reference for this variable. - */ - String getURI(ReadGraph graph) throws DatabaseException; - - /* - * Standard properties - */ - - /** - * @param graph - * @return the unescaped name of this variable. Escaped names are used in URIs. - * @throws DatabaseException if no name is available or other database error occurs - */ - String getName(ReadGraph graph) throws DatabaseException; - - /** - * Informative label of this variable. - * - * @param graph - * @return - * @throws DatabaseException if no label is available or other database error occurs - */ - String getLabel(ReadGraph graph) throws DatabaseException; - /** - * @param graph - * @return parent variable, null for root variable - * @throws DatabaseException - */ - Variable getParent(ReadGraph graph) throws DatabaseException; - - Datatype getDatatype(ReadGraph graph) throws DatabaseException; - Datatype getPossibleDatatype(ReadGraph graph) throws DatabaseException; - - Role getRole(ReadGraph graph) throws DatabaseException; - Role getPossibleRole(ReadGraph graph) throws DatabaseException; - - @Deprecated - Variable getPredicate(ReadGraph graph) throws DatabaseException; - @Deprecated - Variable getPossiblePredicate(ReadGraph graph) throws DatabaseException; - - Resource getPredicateResource(ReadGraph graph) throws DatabaseException; - Resource getPossiblePredicateResource(ReadGraph graph) throws DatabaseException; - - Resource getRepresents(ReadGraph graph) throws DatabaseException; - Resource getPossibleRepresents(ReadGraph graph) throws DatabaseException; - - Resource getType(ReadGraph graph) throws DatabaseException; - Resource getPossibleType(ReadGraph graph) throws DatabaseException; - Resource getType(ReadGraph graph, Resource baseType) throws DatabaseException; - Resource getPossibleType(ReadGraph graph, Resource baseType) throws DatabaseException; - - Set getClassifications(ReadGraph graph) throws DatabaseException; - - RVI getRVI(ReadGraph graph) throws DatabaseException; - RVI getPossibleRVI(ReadGraph graph) throws DatabaseException; - -} +/******************************************************************************* + * Copyright (c) 2007, 2010 Association for Decentralized Information Management + * in Industry THTH ry. + * All rights reserved. This program and the accompanying materials + * are made available under the terms of the Eclipse Public License v1.0 + * which accompanies this distribution, and is available at + * http://www.eclipse.org/legal/epl-v10.html + * + * Contributors: + * VTT Technical Research Centre of Finland - initial API and implementation + *******************************************************************************/ +package org.simantics.db.layer0.variable; + +import java.util.Collection; +import java.util.Set; + +import org.simantics.databoard.binding.Binding; +import org.simantics.databoard.binding.mutable.Variant; +import org.simantics.databoard.type.Datatype; +import org.simantics.db.ReadGraph; +import org.simantics.db.Resource; +import org.simantics.db.WriteGraph; +import org.simantics.db.exception.DatabaseException; +import org.simantics.db.layer0.exception.NonWritableVariableException; +import org.simantics.db.layer0.request.PropertyInfo; +import org.simantics.db.layer0.variable.RVI.RVIPart; +import org.simantics.db.layer0.variable.Variables.Role; + +/* + * Variable is a standard i/o data interface to a model in Simantics. The variable interface provides + * + * - Unified data addressing in string format (URI) + * - Flattening of reusable component hierarchies + * - Runtime values + * - Derived values + * + * The Variable interface spans a tree of variables such that each node can have children and properties. + * - children are denoted by the '/' separator + * - properties are denoted by the '#' separator + * + * There are three kinds of URIs + * + * Variable URI: + * A standard random access identifier to a variable. + * Examples: + * - http://www.asd.org/Projects/AprosModel1/BaseRealization/Diagram/PI_X#PI_MASS_FLOW + * - http://www.asd.org/Projects/AprosModel1/Experiment/UUID/Diagram/PI_X#PI_MASS_FLOW#Unit + * Realization URI: + * A random access identifier to a context under which a valuation of a model is presented. + * A realization URI is guaranteed to have a unique resource obtainable by ReadGraph.getResource() + * Examples: + * - http://www.asd.org/Projects/AprosModel1/BaseRealization + * - http://www.asd.org/Projects/AprosModel1/Experiment/UUID + * Relative Variable Identifier (RVI): + * A reference which can be used to obtain a variable when realization is given + * Examples: + * - /Diagram/PI_X#PI_MASS_FLOW + * - /Diagram/PI_X#PI_MASS_FLOW#Unit + * + * Use cases: + * + * 1. Given a configuration resource and context variable obtain variable + * Procedure: call Variable.browse(ReadGraph, Resource) + * + * 2. Given two variables obtain RVI of second based on first + * Procedure: call Variables.getRVI(Variable, Variable) + * + * 3. Given Realization URI obtain Variable + * Procedure: call ReadGraph.getResource and then adapt(Resource, Variable.class) + * + * 4. Given Realization URI and RVI, obtain Variable + * Procedure: obtain Variable from Realization URI, call Variable.browse(ReadGraph, String) + * + * 5. Given Variable URI, obtain Variable + * Procedure: call Variables.getVariable(ReadGraph, String) + * + * 6. Given Variable, obtain model + * Procedure: call Variables.getModel(ReadGraph, Variable) + * + * 7. Given Variable, obtain realization + * Procedure: call Variables.getRealization(ReadGraph, Variable) + + * 8. Given Variable, obtain Variable in other realization + * Procedure: call Variables.switchRealization(ReadGraph, Variable, Resource) + * + */ + + +public interface Variable { + + /* + * Convenience method for getting the value of a named property. + */ + T getPropertyValue(ReadGraph graph, String name) throws DatabaseException; + T getPropertyValue(ReadGraph graph, Resource property) throws DatabaseException; + T getPossiblePropertyValue(ReadGraph graph, String name) throws DatabaseException; + T getPossiblePropertyValue(ReadGraph graph, Resource property) throws DatabaseException; + /* + * Convenience method for getting the value of a named property. + */ + T getPropertyValue(ReadGraph graph, String name, Binding binding) throws DatabaseException; + T getPropertyValue(ReadGraph graph, Resource property, Binding binding) throws DatabaseException; + T getPossiblePropertyValue(ReadGraph graph, String name, Binding binding) throws DatabaseException; + T getPossiblePropertyValue(ReadGraph graph, Resource property, Binding binding) throws DatabaseException; + /* + * Gets the value of the property. Binding is default. + */ + T getValue(ReadGraph graph) throws DatabaseException; + T getPossibleValue(ReadGraph graph) throws DatabaseException; + /* + * Gets the value of the property. Binding is explicitly given. + */ + T getValue(ReadGraph graph, Binding binding) throws DatabaseException; + T getPossibleValue(ReadGraph graph, Binding binding) throws DatabaseException; + Variant getVariantValue(ReadGraph graph) throws DatabaseException; + + /* + * If role is Property returns the corresponding PropertyInfo. + * @throws DatabaseException if role of this variable is not Property + */ + PropertyInfo getPropertyInfo(ReadGraph graph) throws DatabaseException; + + /** + * @return the index root resource or null if the index root + * cannot be found + * @throws DatabaseException in any other error conditions + */ + Resource getIndexRoot(ReadGraph graph) throws DatabaseException; + + /** + * Writes a value using the given binding. + * + * @throws NonWritableVariableException if the variable is not writable + * @throws DatabaseException in any other error conditions + */ + void setValue(WriteGraph graph, Object value, Binding binding) throws DatabaseException; + /** + * Writes a value with default binding based on the value class. + * + * @throws NonWritableVariableException if the variable is not writable + * @throws DatabaseException in any other error conditions + */ + void setValue(WriteGraph graph, Object value) throws DatabaseException; + + /** + * Writes a value to the given property using the given binding. + * + * @throws NonWritableVariableException if the variable is not writable + * @throws DatabaseException in any other error conditions + */ + void setPropertyValue(WriteGraph graph, String name, Object value, Binding binding) throws DatabaseException; + void setPropertyValue(WriteGraph graph, Resource property, Object value, Binding binding) throws DatabaseException; + /** + * Writes a value to the given property using the default binding based on + * the value class. + * + * @throws NonWritableVariableException if the variable is not writable + * @throws DatabaseException in any other error conditions + */ + void setPropertyValue(WriteGraph graph, String name, Object value) throws DatabaseException; + void setPropertyValue(WriteGraph graph, Resource property, Object value) throws DatabaseException; + + // TODO methods? + + /* + * Gets a named child of this variable. A child corresponds to a '/' in URI notation + */ + Variable getChild(ReadGraph graph, String name) throws DatabaseException; + Variable getPossibleChild(ReadGraph graph, String name) throws DatabaseException; + /* + * Gets a named property of this variable. A property corresponds to a '#' in URI notation + */ + Variable getProperty(ReadGraph graph, String name) throws DatabaseException; + Variable getProperty(ReadGraph graph, Resource property) throws DatabaseException; + Variable getPossibleProperty(ReadGraph graph, String name) throws DatabaseException; + Variable getPossibleProperty(ReadGraph graph, Resource property) throws DatabaseException; + + /* + * Browses all children of this variable. + * @deprecated replaced by {@link #getChildren(ReadGraph)} + */ + @Deprecated + Collection browseChildren(ReadGraph graph) throws DatabaseException; + + /* + * Gets all children of this variable. + */ + Collection getChildren(ReadGraph graph) throws DatabaseException; + + /* + * Browses all available properties of this variable. An empty collection shall + * be returned if there are no properties for this variable. + * @deprecated replaced by {@link #getProperties(ReadGraph)} + */ + @Deprecated + Collection browseProperties(ReadGraph graph) throws DatabaseException; + + /* + * Gets all available properties of this variable. An empty collection shall + * be returned if there are no properties for this variable. + */ + Collection getProperties(ReadGraph graph) throws DatabaseException; + /* + * Gets all properties of this variable such that {@link #getClassifications()} + * contains classification. An empty collection shall + * be returned if there are no properties for this variable. + */ + Collection getProperties(ReadGraph graph, String classification) throws DatabaseException; + Collection getProperties(ReadGraph graph, Resource classification) throws DatabaseException; + + /* + * Browses a single variable using the given suffix path. The suffix can contain various '/' and '#'. + */ + Variable browse(ReadGraph graph, String suffix) throws DatabaseException; + Variable browsePossible(ReadGraph graph, String suffix) throws DatabaseException; + + /* + * Browses a single variable using the given configuration resource. + */ + Variable browse(ReadGraph graph, Resource config) throws DatabaseException; + Variable browsePossible(ReadGraph graph, Resource config) throws DatabaseException; + + Variable resolve(ReadGraph graph, RVIPart part) throws DatabaseException; + Variable resolvePossible(ReadGraph graph, RVIPart part) throws DatabaseException; + + /* + * Gets the requested interface associated to this variable if available. + * Examples: + * -Resource + * -Accessor + * -Binding + * + */ + @Deprecated + T getInterface(ReadGraph graph, Class clazz) throws DatabaseException; + + T adapt(ReadGraph graph, Class clazz) throws DatabaseException; + T adaptPossible(ReadGraph graph, Class clazz) throws DatabaseException; + + /* + * Gets the unique URI reference for this variable. + */ + String getURI(ReadGraph graph) throws DatabaseException; + + /* + * Standard properties + */ + + /** + * @param graph + * @return the unescaped name of this variable. Escaped names are used in URIs. + * @throws DatabaseException if no name is available or other database error occurs + */ + String getName(ReadGraph graph) throws DatabaseException; + + /** + * Informative label of this variable. + * + * @param graph + * @return + * @throws DatabaseException if no label is available or other database error occurs + */ + String getLabel(ReadGraph graph) throws DatabaseException; + /** + * @param graph + * @return parent variable, null for root variable + * @throws DatabaseException + */ + Variable getParent(ReadGraph graph) throws DatabaseException; + + Datatype getDatatype(ReadGraph graph) throws DatabaseException; + Datatype getPossibleDatatype(ReadGraph graph) throws DatabaseException; + + Role getRole(ReadGraph graph) throws DatabaseException; + Role getPossibleRole(ReadGraph graph) throws DatabaseException; + + @Deprecated + Variable getPredicate(ReadGraph graph) throws DatabaseException; + @Deprecated + Variable getPossiblePredicate(ReadGraph graph) throws DatabaseException; + + Resource getPredicateResource(ReadGraph graph) throws DatabaseException; + Resource getPossiblePredicateResource(ReadGraph graph) throws DatabaseException; + + Resource getRepresents(ReadGraph graph) throws DatabaseException; + Resource getPossibleRepresents(ReadGraph graph) throws DatabaseException; + + Resource getType(ReadGraph graph) throws DatabaseException; + Resource getPossibleType(ReadGraph graph) throws DatabaseException; + Resource getType(ReadGraph graph, Resource baseType) throws DatabaseException; + Resource getPossibleType(ReadGraph graph, Resource baseType) throws DatabaseException; + + Set getClassifications(ReadGraph graph) throws DatabaseException; + + RVI getRVI(ReadGraph graph) throws DatabaseException; + RVI getPossibleRVI(ReadGraph graph) throws DatabaseException; + +}