bundles/org.simantics.databoard/src/org/simantics/databoard/accessor/reference/ChildReference.java

   1 /*******************************************************************************\r
   2  *  Copyright (c) 2010 Association for Decentralized Information Management in\r
   3  *  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.databoard.accessor.reference;
  13
  14 import java.io.IOException;\r
  15 import java.util.Collection;\r
  16 import java.util.Iterator;\r
  17 import java.util.StringTokenizer;\r
  18 import java.util.regex.Matcher;\r
  19 import java.util.regex.Pattern;\r
  20 \r
  21 import org.simantics.databoard.Bindings;\r
  22 import org.simantics.databoard.adapter.AdaptException;\r
  23 import org.simantics.databoard.annotations.Optional;\r
  24 import org.simantics.databoard.annotations.Union;\r
  25 import org.simantics.databoard.binding.Binding;\r
  26 import org.simantics.databoard.binding.mutable.MutableVariant;\r
  27 import org.simantics.databoard.type.ArrayType;\r
  28 import org.simantics.databoard.type.Datatype;\r
  29 import org.simantics.databoard.type.MapType;\r
  30 import org.simantics.databoard.type.OptionalType;\r
  31 import org.simantics.databoard.type.RecordType;\r
  32 import org.simantics.databoard.type.UnionType;\r
  33 import org.simantics.databoard.util.URIUtil;\r
  34
  35 /**
  36  * Path is a single or multi-level reference to a child node in the tree \r
  37  * representation of data value. <p>
  38  *
  39  * ComponentReference[] is a path from a node to a child or decendent node
  40  * in the tree representation of the container. <p>
  41  *
  42  * Reference has three serializable formats: Binary, URL compatible Path.
  43  *
  44  * @author Toni Kalajainen <toni.kalajainen@vtt.fi>
  45  */
  46 @Union({
  47                 IndexReference.class,
  48                 KeyReference.class,
  49                 NameReference.class,
  50                 ComponentReference.class, \r
  51                 LabelReference.class
  52         })
  53 public abstract class ChildReference implements Cloneable {
  54 \r
  55         \r
  56         /**\r
  57          * Create a concatenation of two references. Prefix part is cloned,\r
  58          * suffix is linked.\r
  59          * \r
  60          * @param pathToBeCloned prefix path, or <tt>null</tt>\r
  61          * @param ref suffix path, or <tt>null</tt>\r
  62          * @return path\r
  63          */\r
  64         public static ChildReference concatenate(ChildReference pathToBeCloned, ChildReference ref) {\r
  65                 if (pathToBeCloned==null) return ref;\r
  66                 ChildReference result = pathToBeCloned.clone();\r
  67                 if (ref==null) return result;\r
  68                 result.tail().setChildReference(ref);\r
  69                 return result;\r
  70         }\r
  71         \r
  72         /**\r
  73          * Creates a compilation of individual a references into a one refence. \r
  74          *  \r
  75          * @param refs\r
  76          * @return reference or <code>null</code> if there are no elements\r
  77          */\r
  78         public static ChildReference compile(ChildReference ... refs) {\r
  79                 if (refs.length==0) return null;\r
  80                 ChildReference first = refs[0].clone();\r
  81                 ChildReference r = first;\r
  82                 for (int i=1; i<refs.length; i++) {\r
  83                         ChildReference next = refs[i].clone();\r
  84                         r.setChildReference( next );\r
  85                         r = next;\r
  86                         while(r.childReference!=null) r = r.childReference;\r
  87                 }\r
  88                 return first;\r
  89         }\r
  90 \r
  91         /**\r
  92          * Creates a compilation of individual a references into a one refence. \r
  93          *  \r
  94          * @param refs\r
  95          * @return reference or <code>null</code> if there are no elements\r
  96          */\r
  97         public static ChildReference compile(Collection<ChildReference> refs) {\r
  98                 if (refs.isEmpty()) return null;\r
  99                 Iterator<ChildReference> itr = refs.iterator();\r
 100                 ChildReference first = itr.next().clone();\r
 101                 ChildReference r = first;\r
 102                 for (; itr.hasNext(); ) {\r
 103                         ChildReference next = itr.next().clone();\r
 104                         r.setChildReference( next );\r
 105                         r = next;\r
 106                         while(r.childReference!=null) r = r.childReference;\r
 107                 }\r
 108                 return first;\r
 109         }\r
 110 \r
 111         /**\r
 112          * Get reference path from AccessorReference path.\r
 113          * <a href="http://dev.simantics.org/index.php/Databoard_Specification#Path_Notation">Path Notation</a>\r
 114          * \r
 115          * @param path\r
 116          * @return reference path or <code>null</code> if there is no path\r
 117          */\r
 118         public static ChildReference parsePath(String path) {\r
 119                 StringTokenizer st = new StringTokenizer(path, "/", false);\r
 120                 if (!st.hasMoreTokens()) return null;\r
 121                 ChildReference first = createSingleReference( st.nextToken() );         \r
 122                 ChildReference ref = first;\r
 123                 while (st.hasMoreTokens()) {\r
 124                         ref.childReference = createSingleReference(st.nextToken());\r
 125                         ref = ref.childReference;\r
 126                 }\r
 127                 \r
 128                 return first;\r
 129         }\r
 130         \r
 131         /**\r
 132          * Attempt to convert value reference to type reference.  \r
 133          * \r
 134          * @param vref\r
 135          * @param type\r
 136          * @return type reference or null\r
 137          * @throws IllegalArgumentException if conversion fails.\r
 138          */\r
 139         public static ChildReference toTypeReference(ChildReference vref, Datatype type) \r
 140         throws IllegalArgumentException \r
 141         {\r
 142                 if (vref==null) return null;\r
 143                 if (type instanceof ArrayType) {\r
 144                         if (vref instanceof IndexReference || vref instanceof LabelReference) {\r
 145                                 ChildReference tail = toTypeReference( vref.childReference, type.getComponentType(0) );\r
 146                                 return new ComponentReference( tail );\r
 147                         }\r
 148                 }\r
 149                 \r
 150                 if (type instanceof MapType) {\r
 151                         if (vref instanceof KeyReference) {\r
 152                                 ChildReference tail = toTypeReference( vref.childReference, type.getComponentType(1) );\r
 153                                 return new IndexReference( 1, tail );                           \r
 154                         }\r
 155                 }\r
 156                 \r
 157                 if (type instanceof OptionalType) {\r
 158                         if (vref instanceof ComponentReference) {\r
 159                                 ChildReference tail = toTypeReference( vref.childReference, type.getComponentType(0) );\r
 160                                 return new ComponentReference( tail );                          \r
 161                         }\r
 162                         if (vref instanceof LabelReference) {\r
 163                                 LabelReference lr = (LabelReference) vref;\r
 164                                 if (lr.label.equals("v")) {\r
 165                                         ChildReference tail = toTypeReference( vref.childReference, type.getComponentType(0) );\r
 166                                         return new ComponentReference( tail );\r
 167                                 }\r
 168                         }                       \r
 169                 }\r
 170                 \r
 171                 if (type instanceof RecordType) {\r
 172                         RecordType rt = (RecordType) type;\r
 173                         if (vref instanceof IndexReference) {\r
 174                                 IndexReference ir = (IndexReference) vref;                              \r
 175                                 ChildReference tail = toTypeReference( vref.childReference, type.getComponentType(ir.index) );\r
 176                                 return new IndexReference( ir.index, tail );\r
 177                         }\r
 178                         \r
 179                         if (vref instanceof NameReference) {\r
 180                                 NameReference ir = (NameReference) vref;                                \r
 181                                 ChildReference tail = toTypeReference( vref.childReference, rt.getComponentType(ir.name) );\r
 182                                 return new NameReference( ir.name, tail );\r
 183                         }\r
 184                         \r
 185                         if (vref instanceof LabelReference) {\r
 186                                 LabelReference ir = (LabelReference) vref;                              \r
 187                                 ChildReference tail = toTypeReference( vref.childReference, rt.getComponentType(ir.label) );\r
 188                                 return new NameReference( ir.label, tail );\r
 189                         }                       \r
 190                 }\r
 191                 \r
 192                 if (type instanceof UnionType) {\r
 193                         UnionType ut = (UnionType) type;\r
 194                         if (vref instanceof IndexReference) {\r
 195                                 IndexReference ir = (IndexReference) vref;                              \r
 196                                 ChildReference tail = toTypeReference( vref.childReference, type.getComponentType(ir.index) );\r
 197                                 return new IndexReference( ir.index, tail );\r
 198                         }\r
 199                         \r
 200                         if (vref instanceof NameReference) {\r
 201                                 NameReference ir = (NameReference) vref;                                \r
 202                                 ChildReference tail = toTypeReference( vref.childReference, ut.getComponentType(ir.name) );\r
 203                                 return new NameReference( ir.name, tail );\r
 204                         }\r
 205                         \r
 206                         if (vref instanceof LabelReference) {\r
 207                                 LabelReference ir = (LabelReference) vref;                              \r
 208                                 ChildReference tail = toTypeReference( vref.childReference, ut.getComponentType(ir.label) );\r
 209                                 return new NameReference( ir.label, tail );\r
 210                         }                       \r
 211                 }\r
 212                 \r
 213                 \r
 214                 throw new IllegalArgumentException();\r
 215         }\r
 216         \r
 217         public static ChildReference parseBinary(byte[] binaryRef) \r
 218         throws IOException \r
 219         {\r
 220                 Binding binding = Bindings.getBindingUnchecked(ChildReference.class);\r
 221                 ChildReference result;\r
 222                 result = (ChildReference) Bindings.getSerializerUnchecked( binding ).deserialize(binaryRef);\r
 223                 return result;\r
 224         }\r
 225         \r
 226         public final static Pattern INDEX_PATTERN = Pattern.compile("i-(\\d*)");\r
 227         public final static Pattern MAP_PATTERN = Pattern.compile("k-(\\p{ASCII}*)");\r
 228         public final static Pattern NAME_PATTERN = Pattern.compile("n-(\\p{ASCII}*)");\r
 229
 230         public @Optional ChildReference childReference;
 231
 232         protected ChildReference() {}
 233
 234         protected ChildReference(ChildReference childReference) {
 235                 this.childReference = childReference;
 236         }
 237
 238         public ChildReference getChildReference() {
 239                 return childReference;
 240         }\r
 241         \r
 242         public boolean hasChildReference() {\r
 243                 return childReference != null;\r
 244         }\r
 245
 246         public void setChildReference(ChildReference childReference) {
 247                 this.childReference = childReference;
 248         }\r
 249 \r
 250         public int getDepth() {\r
 251                 int result = 1;\r
 252                 ChildReference r = this;\r
 253                 while ( r.childReference != null ) {\r
 254                         r = r.childReference;\r
 255                         result++;\r
 256                 }\r
 257                 return result;\r
 258         }\r
 259         \r
 260         public String toPath() {\r
 261                 return toPath(true);\r
 262         }\r
 263         \r
 264         /**\r
 265          * Converts the reference path into string representation.\r
 266          * \r
 267          * @param labelReference if true return label references.\r
 268          * @return path string representation\r
 269          */\r
 270         public String toPath(boolean labelReference) {\r
 271                 if (childReference == null) return toString();\r
 272                 StringBuilder sb = new StringBuilder();\r
 273                 ChildReference ref = this;\r
 274                 while (ref!=null) {\r
 275                         if (sb.length() > 0) sb.append("/");\r
 276                         sb.append( ref.toString(labelReference) );\r
 277                         ref = ref.getChildReference();\r
 278                 }\r
 279                 return sb.toString();\r
 280         }\r
 281         \r
 282         /**\r
 283          * Convert the reference into its string representation\r
 284          * \r
 285          * @return reference string representation\r
 286          */
 287         public String toString() {\r
 288                 return toString(true);\r
 289         }\r
 290         \r
 291         /**\r
 292          * Convert the reference into string representation.<p>\r
 293          *\r
 294          * If <code>labelReference</code> is true, the string representation is\r
 295          * more user readable but has weaker typing. It serializes into\r
 296          * instances of LabelReference.\r
 297          * \r
 298          * For instance Record Field Reference is "n-Children", but label reference "Children".\r
 299          * \r
 300          * Some references cannot be converted into LabelReference. \r
 301          * E.g. string representation of FieldNameReference("i-5") is ambiguous with ArrayIndexReference(5). \r
 302          * \r
 303          * @param labelReference if true returns  \r
 304          * @return string representation \r
 305          */\r
 306         public abstract String toString(boolean labelReference); \r
 307 \r
 308         public abstract ChildReference clone();
 309
 310         public ChildReference tail() {
 311                 ChildReference result = this;
 312                 while (result.childReference!=null) result = result.childReference;
 313                 return result;
 314         }
 315         \r
 316         /**\r
 317          * Create accessor reference from string representation.\r
 318          * This doesn't parse path separators.\r
 319          * \r
 320          * @see https://www.simantics.org/wiki/index.php/Databoard_Specification#Accessor_Reference\r
 321          * \r
 322          * @param ref\r
 323          * @return\r
 324          */\r
 325         static ChildReference createSingleReference(String ref) {\r
 326                 Matcher m;\r
 327                 \r
 328                 m = INDEX_PATTERN.matcher( ref );\r
 329                 if (m.matches()) {\r
 330                         return new IndexReference( Integer.parseInt( m.group(1) ) );\r
 331                 }\r
 332                 \r
 333                 m = MAP_PATTERN.matcher( ref );\r
 334                 if (m.matches()) {\r
 335                         String keyStr = m.group(1);\r
 336                         MutableVariant key;\r
 337                         try {\r
 338                                 key = (MutableVariant) Bindings.adapt(keyStr, Bindings.STRING, Bindings.MUTABLE_VARIANT);\r
 339                         } catch (AdaptException e) {\r
 340                                 throw new IllegalArgumentException("Not string variant "+ref, e);\r
 341                         }\r
 342                         return new KeyReference(key);\r
 343                 }\r
 344                 \r
 345                 m = NAME_PATTERN.matcher( ref );\r
 346                 if (m.matches()) {\r
 347                         String encoded = m.group(1);\r
 348                         String name = URIUtil.decodeURI(encoded);\r
 349                         return new NameReference( name );\r
 350                 }\r
 351                 \r
 352                 if (ref.equals("v")) {\r
 353                         return new ComponentReference();\r
 354                 }\r
 355                 \r
 356                 String text = URIUtil.decodeURI( ref );\r
 357                 return new LabelReference( text );              \r
 358         }
 359
 360 }
 361