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

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