--- /dev/null
+/*******************************************************************************\r
+ * Copyright (c) 2007, 2010 Association for Decentralized Information Management\r
+ * in Industry THTH ry.\r
+ * All rights reserved. This program and the accompanying materials\r
+ * are made available under the terms of the Eclipse Public License v1.0\r
+ * which accompanies this distribution, and is available at\r
+ * http://www.eclipse.org/legal/epl-v10.html\r
+ *\r
+ * Contributors:\r
+ * VTT Technical Research Centre of Finland - initial API and implementation\r
+ *******************************************************************************/\r
+package org.simantics.modeling.services;\r
+\r
+import java.util.List;\r
+import java.util.Set;\r
+\r
+import org.simantics.db.ReadGraph;\r
+import org.simantics.db.Resource;\r
+import org.simantics.db.exception.DatabaseException;\r
+import org.simantics.project.IProject;\r
+import org.simantics.project.IProjectService;\r
+import org.simantics.utils.datastructures.hints.IHintContext.Key;\r
+import org.simantics.utils.datastructures.hints.IHintContext.KeyOf;\r
+\r
+/**\r
+ * Defines a strategy for naming components in a normal structural model.\r
+ * \r
+ * <p>\r
+ * The purpose of this interface is to allow different naming conventions for\r
+ * different modelling domains. Almost always it is necessary to make names\r
+ * unique within a certain context. The context may be either the whole model\r
+ * (all structural levels) or perhaps within a single composite component.\r
+ * \r
+ * <p>\r
+ * To put your own naming strategy into use, please set it into the active\r
+ * {@link IProject} using the {@link #PROJECT_KEY} hint key.\r
+ * \r
+ * <p>\r
+ * Implementations must be thread-safe. Implementations should not return the\r
+ * same name twice, a least not within a small time-window. Since holding a set\r
+ * of all returned names cannot be held in memory indefinitely, names that\r
+ * have been returned but are not actually in use may be reused.\r
+ * \r
+ * @author Tuukka Lehtonen\r
+ */\r
+public interface ComponentNamingStrategy extends IProjectService {\r
+\r
+ /**\r
+ * A key used for storing a project-local {@link ComponentNamingStrategy}\r
+ * within an {@link IProject}.\r
+ */\r
+ Key PROJECT_KEY = new KeyOf(ComponentNamingStrategy.class);\r
+\r
+ /**\r
+ * Finds a unique name for a new instance of the specified component type\r
+ * within the context of the specified configuration element.\r
+ * \r
+ * @param graph\r
+ * @param configurationRoot\r
+ * @param container\r
+ * @param componentType\r
+ * @return a unique component name within the specified context and the\r
+ * specified component type\r
+ * @throws NamingException if a fresh name cannot be resolved, possibly out\r
+ * of names\r
+ * @throws DatabaseException in case of any database errors\r
+ */\r
+ String findFreshInstanceName(\r
+ ReadGraph graph,\r
+ Resource configurationRoot,\r
+ Resource container,\r
+ Resource componentType)\r
+ throws NamingException, DatabaseException;\r
+\r
+ /**\r
+ * Validates the given proposition for the given component\r
+ * \r
+ * @param graph\r
+ * @param configurationRoot\r
+ * @param component\r
+ * @param proposition\r
+ * @return a unique component name within the specified context based on the\r
+ * specified name proposition and possibly the component type\r
+ * @throws NamingException if the specified name is invalid and cannot be\r
+ * made valid\r
+ * @throws DatabaseException in case of any database errors\r
+ */\r
+ String validateInstanceName(\r
+ ReadGraph graph,\r
+ Resource configurationRoot,\r
+ Resource component,\r
+ String proposition,\r
+ boolean acceptProposition)\r
+ throws NamingException, DatabaseException;\r
+ \r
+ /**\r
+ * Validates the specified name proposition. Finds a unique name for a new\r
+ * instance of the specified component type within the context of the\r
+ * specified configuration element.\r
+ * \r
+ * @param graph\r
+ * @param configurationRoot\r
+ * @param container\r
+ * @param componentType\r
+ * @param proposition\r
+ * @return a unique component name within the specified context based on the\r
+ * specified name proposition and possibly the component type\r
+ * @throws NamingException if the specified name is invalid and cannot be\r
+ * made valid\r
+ * @throws DatabaseException in case of any database errors\r
+ */\r
+ String validateInstanceName(\r
+ ReadGraph graph,\r
+ Resource configurationRoot,\r
+ Resource container,\r
+ Resource componentType,\r
+ String proposition)\r
+ throws NamingException, DatabaseException;\r
+\r
+ /**\r
+ * Validates the specified name proposition. Finds a unique name for a new\r
+ * instance of the specified component type within the context of the\r
+ * specified configuration element.\r
+ * \r
+ * @param graph\r
+ * @param configurationRoot\r
+ * @param container\r
+ * @param componentType\r
+ * @param proposition name proposition to validate\r
+ * @param acceptProposition <code>true</code> if proposition as such is\r
+ * considered an accepted value, <code>false</code> if not\r
+ * @return a unique component name within the specified context based on the\r
+ * specified name proposition and possibly the component type\r
+ * @throws NamingException if the specified name is invalid and cannot be\r
+ * made valid\r
+ * @throws DatabaseException in case of any database errors\r
+ */\r
+ String validateInstanceName(\r
+ ReadGraph graph,\r
+ Resource configurationRoot,\r
+ Resource container,\r
+ Resource componentType,\r
+ String proposition,\r
+ boolean acceptProposition)\r
+ throws NamingException, DatabaseException;\r
+\r
+ /**\r
+ * Validates the specified list of name propositions. Finds a unique name\r
+ * for each listed proposition so that the returned names don't collide with\r
+ * existing names in the model configuration and they don't collide with\r
+ * each other.\r
+ * <p>\r
+ * This method shall not reserve the returned names so that later\r
+ * invocations to any methods in this interface would not return the same\r
+ * names. It is the callers responsibility to handle that this method is\r
+ * either invoked within a write transaction to ensure that no other party\r
+ * validates names simultaneously or otherwise make sure that there are no\r
+ * problems through UI design.\r
+ * \r
+ * @param graph\r
+ * @param configurationRoot\r
+ * @param propositions\r
+ * list of name propositions to validate\r
+ * @param acceptProposition\r
+ * <code>true</code> if proposition as such is considered an\r
+ * accepted value, <code>false</code> if not\r
+ * @param externallyReserved\r
+ * a collection of names that are to be considered externally\r
+ * reserved that the validated names shall not collide with. May\r
+ * be <code>null</code> to specify no externally reserved names.\r
+ * @return unique names to match each provided proposition in the same\r
+ * order. The returned names shall not collide with existing names\r
+ * in the configuration nor each other.\r
+ * @throws NamingException\r
+ * if the specified name is invalid and cannot be made valid\r
+ * @throws DatabaseException\r
+ * in case of any database errors\r
+ */\r
+ List<String> validateInstanceNames(\r
+ ReadGraph graph,\r
+ Resource configurationRoot,\r
+ List<String> propositions,\r
+ boolean acceptProposition,\r
+ Set<String> externallyReserved)\r
+ throws NamingException, DatabaseException;\r
+\r
+}\r
Code Review / simantics / platform.git / blobdiff