--- /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.browsing.ui;\r
+\r
+import java.util.Arrays;\r
+import java.util.Set;\r
+\r
+import org.eclipse.core.runtime.IAdaptable;\r
+\r
+/**\r
+ * A context used to represent a single visible UI item.\r
+ * \r
+ * <p>\r
+ * An INodeContext can be initialized to contain multiple constants accessible\r
+ * with {@link ConstantKey}s through {@link #getConstant(ConstantKey)}.\r
+ * </p>\r
+ * <p>\r
+ * It is vital that every instance of INodeContext contains a constant with the\r
+ * {@link ConstantKey} {@link BuiltinKeys#INPUT}, since that data is used all\r
+ * over the graph explorer framework for resolving labelers, imager, decorators\r
+ * and others.\r
+ * </p>\r
+ * \r
+ * <p>\r
+ * INodeContext must implement {@link #equals(Object)} and {@link #hashCode()}\r
+ * to enable the graph explorer to work properly.\r
+ * </p>\r
+ * \r
+ * @see NodeContextBuilder\r
+ * @see NodeContextUtil\r
+ */\r
+public interface NodeContext extends IAdaptable {\r
+\r
+ NodeContext[] NONE = new NodeContext[0];\r
+\r
+ /**\r
+ * A key interface used for querying constants from INodeContext. Create\r
+ * static instances of this interface to create re-usable keys.\r
+ * \r
+ * <p>\r
+ * See {@link BuiltinKeys} for standard concrete keys used in the\r
+ * implementations\r
+ * \r
+ * @param <T> type of the value stored with this key.\r
+ * \r
+ * See NodeContextBuilder\r
+ */\r
+ public static interface ConstantKey<T> {}\r
+\r
+ /**\r
+ * @param <T> the type of the value designated by the specified key\r
+ * @param key\r
+ * @return the value with the specified key or <code>null</code> there was\r
+ * no value for the key\r
+ * @throws ClassCastException if the key stored in the node is does not\r
+ * match T. This should not happen.\r
+ */\r
+ <T> T getConstant(ConstantKey<T> key);\r
+ Set<ConstantKey<?>> getKeys();\r
+\r
+ /**\r
+ * Do not implement this directly, look at {@link PrimitiveQueryKey} and\r
+ * {@link QueryKey} instead.\r
+ */\r
+ public static interface CacheKey<T> {\r
+ /**\r
+ * This method must return a unique object that is used to decide which\r
+ * QueryProcessor is used to calculate the query result.\r
+ * \r
+ * The returned value is compared only using object identity (==), not\r
+ * equals.\r
+ * \r
+ * @return the identifier of this processor\r
+ */\r
+ Object processorIdenfitier();\r
+ }\r
+\r
+ /**\r
+ * This key class is used for <i>non-leaf</i> queries that only functionally\r
+ * perform other queries to produce their result.\r
+ * \r
+ * <p>\r
+ * These are always cleared (invalidated) or updated inside the query\r
+ * manager. The methods available in {@link NodeQueryManager} are the only\r
+ * methods within the query system that the query implementation can use. It\r
+ * cannot perform lazy evaluation.\r
+ * \r
+ * @see NodeQueryManager\r
+ * @see NodeQueryProcessor\r
+ */\r
+ public static abstract class QueryKey<T> implements CacheKey<T> {\r
+ @Override\r
+ public Object processorIdenfitier() {\r
+ return this;\r
+ }\r
+ }\r
+\r
+ /**\r
+ * Primitive query keys are used only for <i>leaf</i> queries that do not\r
+ * perform more queries. Only these queries are updated from external\r
+ * sources that are registered through\r
+ * {@link GraphExplorer#setDataSource(DataSource)}.\r
+ * \r
+ * <p>\r
+ * The difference between these queries and {@link QueryKey} queries is that\r
+ * these queries cannot do any further queries, which is already prohibited\r
+ * by the only available interface, {@link PrimitiveQueryUpdater}. Instead\r
+ * these queries can use the\r
+ * {@link PrimitiveQueryUpdater#scheduleReplace(NodeContext, PrimitiveQueryKey, T)}\r
+ * method to store concrete values within the query manager and possibly\r
+ * replace them later when lazy evaluation has completed. Replacing a lazily\r
+ * evaluated result will automatically invalidate all queries depending on\r
+ * this result, also causing the UI to respond to the changes.\r
+ * \r
+ * @see PrimitiveQueryUpdater\r
+ * @see PrimitiveQueryProcessor\r
+ */\r
+ public static abstract class PrimitiveQueryKey<T> implements CacheKey<T> {\r
+ @Override\r
+ public Object processorIdenfitier() {\r
+ return this;\r
+ }\r
+ }\r
+\r
+ /**\r
+ * This primitive query key implementation can be used for passing other\r
+ * parameters to primitive queries besides the input {@link NodeContext}.\r
+ * \r
+ * <p>\r
+ * The extending class must implement the getKeyName() method to provide a\r
+ * human-readable name for the key that is used in the default\r
+ * {@link #toString()} implementation.\r
+ * \r
+ * <p>\r
+ * This class uses the class object as the default processor identifier\r
+ * object (see {@link CacheKey#processorIdenfitier()}. This should work\r
+ * out-of-the-box for most cases and need not be customized.\r
+ */\r
+ public abstract static class ParametrizedPrimitiveQueryKey<T> extends PrimitiveQueryKey<T> {\r
+ private final Object[] parameters;\r
+ private final int hash;\r
+ protected ParametrizedPrimitiveQueryKey(Object ... parameters) {\r
+ this.parameters = parameters;\r
+ this.hash = hash();\r
+ }\r
+\r
+ @Override\r
+ public Object processorIdenfitier() {\r
+ return getClass();\r
+ }\r
+\r
+ @Override\r
+ public String toString() {\r
+ return getKeyName() + Arrays.toString(parameters);\r
+ }\r
+\r
+ /**\r
+ * @param <P> the assumed type of the parameter object\r
+ * @param index the index of the reqeusted parameter\r
+ * @return the parameter with the specified index\r
+ * @throws ClassCastException if the key stored in the node is does not\r
+ * match P.\r
+ * @throws ArrayIndexOutOfBoundsException if a parameter with the\r
+ * specified index is not availble.\r
+ */\r
+ @SuppressWarnings("unchecked")\r
+ public <P> P getParameter(int index) {\r
+ return (P) parameters[index];\r
+ }\r
+\r
+ public abstract String getKeyName();\r
+\r
+ /**\r
+ * Calculates the hash value for this key. The default implementation is\r
+ * based on the hash of the actual key class and the hash of the\r
+ * parameters.\r
+ * \r
+ * @return the hash value\r
+ */\r
+ protected int hash() {\r
+ return getClass().hashCode() * 31 + Arrays.hashCode(parameters);\r
+ }\r
+\r
+ @Override\r
+ public boolean equals(Object obj) {\r
+ if (this == obj)\r
+ return true;\r
+ if (obj == null)\r
+ return false;\r
+ if (getClass() != obj.getClass())\r
+ return false;\r
+ ParametrizedPrimitiveQueryKey<?> o = (ParametrizedPrimitiveQueryKey<?>) obj;\r
+ return Arrays.equals(parameters, o.parameters);\r
+ }\r
+\r
+ @Override\r
+ public int hashCode() {\r
+ return hash;\r
+ }\r
+ }\r
+\r
+}\r
Code Review / simantics / platform.git / blobdiff