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