bundles/org.simantics.modeling/src/org/simantics/modeling/services/ComponentNamingStrategy.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.modeling.services;
  13
  14 import java.util.List;
  15 import java.util.Set;
  16
  17 import org.simantics.db.ReadGraph;
  18 import org.simantics.db.Resource;
  19 import org.simantics.db.exception.DatabaseException;
  20 import org.simantics.project.IProject;
  21 import org.simantics.project.IProjectService;
  22 import org.simantics.utils.datastructures.hints.IHintContext.Key;
  23 import org.simantics.utils.datastructures.hints.IHintContext.KeyOf;
  24
  25 /**
  26  * Defines a strategy for naming components in a normal structural model.
  27  *
  28  * <p>
  29  * The purpose of this interface is to allow different naming conventions for
  30  * different modelling domains. Almost always it is necessary to make names
  31  * unique within a certain context. The context may be either the whole model
  32  * (all structural levels) or perhaps within a single composite component.
  33  *
  34  * <p>
  35  * To put your own naming strategy into use, please set it into the active
  36  * {@link IProject} using the {@link #PROJECT_KEY} hint key.
  37  *
  38  * <p>
  39  * Implementations must be thread-safe. Implementations should not return the
  40  * same name twice, a least not within a small time-window. Since holding a set
  41  * of all returned names cannot be held in memory indefinitely, names that
  42  * have been returned but are not actually in use may be reused.
  43  *
  44  * @author Tuukka Lehtonen
  45  */
  46 public interface ComponentNamingStrategy extends IProjectService {
  47
  48     /**
  49      * A key used for storing a project-local {@link ComponentNamingStrategy}
  50      * within an {@link IProject}.
  51      */
  52     Key PROJECT_KEY = new KeyOf(ComponentNamingStrategy.class);
  53
  54     /**
  55      * Finds a unique name for a new instance of the specified component type
  56      * within the context of the specified configuration element.
  57      *
  58      * @param graph
  59      * @param configurationRoot
  60      * @param container
  61      * @param componentType
  62      * @return a unique component name within the specified context and the
  63      *         specified component type
  64      * @throws NamingException if a fresh name cannot be resolved, possibly out
  65      *         of names
  66      * @throws DatabaseException in case of any database errors
  67      */
  68     String findFreshInstanceName(
  69             ReadGraph graph,
  70             Resource configurationRoot,
  71             Resource container,
  72             Resource componentType)
  73     throws NamingException, DatabaseException;
  74
  75     /**
  76      * Validates the given proposition for the given component
  77      *
  78      * @param graph
  79      * @param configurationRoot
  80      * @param component
  81      * @param proposition
  82      * @return a unique component name within the specified context based on the
  83      *         specified name proposition and possibly the component type
  84      * @throws NamingException if the specified name is invalid and cannot be
  85      *         made valid
  86      * @throws DatabaseException in case of any database errors
  87      */
  88     String validateInstanceName(
  89             ReadGraph graph,
  90             Resource configurationRoot,
  91             Resource component,
  92             String proposition,
  93             boolean acceptProposition)
  94     throws NamingException, DatabaseException;
  95
  96     /**
  97      * Validates the specified name proposition. Finds a unique name for a new
  98      * instance of the specified component type within the context of the
  99      * specified configuration element.
 100      *
 101      * @param graph
 102      * @param configurationRoot
 103      * @param container
 104      * @param componentType
 105      * @param proposition
 106      * @return a unique component name within the specified context based on the
 107      *         specified name proposition and possibly the component type
 108      * @throws NamingException if the specified name is invalid and cannot be
 109      *         made valid
 110      * @throws DatabaseException in case of any database errors
 111      */
 112     String validateInstanceName(
 113             ReadGraph graph,
 114             Resource configurationRoot,
 115             Resource container,
 116             Resource componentType,
 117             String proposition)
 118     throws NamingException, DatabaseException;
 119
 120     /**
 121      * Validates the specified name proposition. Finds a unique name for a new
 122      * instance of the specified component type within the context of the
 123      * specified configuration element.
 124      *
 125      * @param graph
 126      * @param configurationRoot
 127      * @param container
 128      * @param componentType
 129      * @param proposition name proposition to validate
 130      * @param acceptProposition <code>true</code> if proposition as such is
 131      *        considered an accepted value, <code>false</code> if not
 132      * @return a unique component name within the specified context based on the
 133      *         specified name proposition and possibly the component type
 134      * @throws NamingException if the specified name is invalid and cannot be
 135      *         made valid
 136      * @throws DatabaseException in case of any database errors
 137      */
 138     String validateInstanceName(
 139             ReadGraph graph,
 140             Resource configurationRoot,
 141             Resource container,
 142             Resource componentType,
 143             String proposition,
 144             boolean acceptProposition)
 145     throws NamingException, DatabaseException;
 146
 147     /**
 148      * Validates the specified list of name propositions. Finds a unique name
 149      * for each listed proposition so that the returned names don't collide with
 150      * existing names in the model configuration and they don't collide with
 151      * each other.
 152      * <p>
 153      * This method shall not reserve the returned names so that later
 154      * invocations to any methods in this interface would not return the same
 155      * names. It is the callers responsibility to handle that this method is
 156      * either invoked within a write transaction to ensure that no other party
 157      * validates names simultaneously or otherwise make sure that there are no
 158      * problems through UI design.
 159      *
 160      * @param graph
 161      * @param configurationRoot
 162      * @param propositions
 163      *            list of name propositions to validate
 164      * @param acceptProposition
 165      *            <code>true</code> if proposition as such is considered an
 166      *            accepted value, <code>false</code> if not
 167      * @param externallyReserved
 168      *            a collection of names that are to be considered externally
 169      *            reserved that the validated names shall not collide with. May
 170      *            be <code>null</code> to specify no externally reserved names.
 171      * @return unique names to match each provided proposition in the same
 172      *         order. The returned names shall not collide with existing names
 173      *         in the configuration nor each other.
 174      * @throws NamingException
 175      *             if the specified name is invalid and cannot be made valid
 176      * @throws DatabaseException
 177      *             in case of any database errors
 178      */
 179     List<String> validateInstanceNames(
 180             ReadGraph graph,
 181             Resource configurationRoot,
 182             List<String> propositions,
 183             boolean acceptProposition,
 184             Set<String> externallyReserved)
 185     throws NamingException, DatabaseException;
 186
 187 }