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