1 /*******************************************************************************
2 * Copyright (c) 2007, 2010 Association for Decentralized Information Management
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
10 * VTT Technical Research Centre of Finland - initial API and implementation
11 *******************************************************************************/
12 package org.simantics.modeling.services;
14 import java.util.List;
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;
26 * Defines a strategy for naming components in a normal structural model.
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.
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.
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.
44 * @author Tuukka Lehtonen
46 public interface ComponentNamingStrategy extends IProjectService {
49 * A key used for storing a project-local {@link ComponentNamingStrategy}
50 * within an {@link IProject}.
52 Key PROJECT_KEY = new KeyOf(ComponentNamingStrategy.class);
55 * Finds a unique name for a new instance of the specified component type
56 * within the context of the specified configuration element.
59 * @param configurationRoot
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
66 * @throws DatabaseException in case of any database errors
68 String findFreshInstanceName(
70 Resource configurationRoot,
72 Resource componentType)
73 throws NamingException, DatabaseException;
76 * Validates the given proposition for the given component
79 * @param configurationRoot
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
86 * @throws DatabaseException in case of any database errors
88 String validateInstanceName(
90 Resource configurationRoot,
93 boolean acceptProposition)
94 throws NamingException, DatabaseException;
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.
102 * @param configurationRoot
104 * @param componentType
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
110 * @throws DatabaseException in case of any database errors
112 String validateInstanceName(
114 Resource configurationRoot,
116 Resource componentType,
118 throws NamingException, DatabaseException;
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.
126 * @param configurationRoot
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
136 * @throws DatabaseException in case of any database errors
138 String validateInstanceName(
140 Resource configurationRoot,
142 Resource componentType,
144 boolean acceptProposition)
145 throws NamingException, DatabaseException;
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
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.
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
179 List<String> validateInstanceNames(
181 Resource configurationRoot,
182 List<String> propositions,
183 boolean acceptProposition,
184 Set<String> externallyReserved)
185 throws NamingException, DatabaseException;