bundles/org.simantics.databoard/src/org/simantics/databoard/Accessors.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;
  13
  14 import java.io.File;
  15 import java.io.IOException;
  16 import java.nio.ByteBuffer;
  17 import java.util.concurrent.Executor;
  18
  19 import org.simantics.databoard.accessor.Accessor;
  20 import org.simantics.databoard.accessor.ArrayAccessor;
  21 import org.simantics.databoard.accessor.binary.BinaryArray;
  22 import org.simantics.databoard.accessor.binary.BinaryObject;
  23 import org.simantics.databoard.accessor.binary.BinaryStreamArray;
  24 import org.simantics.databoard.accessor.binary.BinaryVariableWidthStreamArray;
  25 import org.simantics.databoard.accessor.error.AccessorConstructionException;
  26 import org.simantics.databoard.accessor.error.AccessorException;
  27 import org.simantics.databoard.accessor.file.FileAccessor;
  28 import org.simantics.databoard.accessor.file.FileArrayAccessor;
  29 import org.simantics.databoard.accessor.file.FileLibrary;
  30 import org.simantics.databoard.accessor.file.FileVariantAccessor;
  31 import org.simantics.databoard.accessor.impl.AccessorParams;
  32 import org.simantics.databoard.accessor.impl.DirectoryMap;
  33 import org.simantics.databoard.accessor.java.JavaObject;
  34 import org.simantics.databoard.accessor.reference.ChildReference;
  35 import org.simantics.databoard.binding.Binding;
  36 import org.simantics.databoard.binding.error.BindingConstructionException;
  37 import org.simantics.databoard.binding.error.BindingException;
  38 import org.simantics.databoard.binding.mutable.Variant;
  39 import org.simantics.databoard.serialization.Serializer;
  40 import org.simantics.databoard.serialization.SerializerConstructionException;
  41 import org.simantics.databoard.type.ArrayType;
  42 import org.simantics.databoard.type.Datatype;
  43 import org.simantics.databoard.util.binary.BinaryFile;
  44 import org.simantics.databoard.util.binary.BinaryMemory;
  45 import org.simantics.databoard.util.binary.Blob;
  46 import org.simantics.databoard.util.binary.RandomAccessBinary;
  47
  48 /**
  49  * This is a facade class for accessor services.
  50  *
  51  * @author Toni Kalajainen <toni.kalajainen@vtt.fi>
  52  */
  53 public class Accessors {
  54
  55         /**
  56          * Open an accessor to byte data.
  57          *
  58          * @param binary
  59          * @param type
  60          * @param params
  61          * @return an accessor
  62          * @throws AccessorConstructionException
  63          */
  64         @SuppressWarnings("unchecked")
  65         public static <T extends Accessor> T getAccessor(RandomAccessBinary binary, Datatype type, AccessorParams params) throws AccessorConstructionException {
  66                 return (T) BinaryObject.createAccessor(binary, type, params);
  67         }
  68
  69         /**
  70          * Open an accessor to byte data.
  71          *
  72          * @param binary
  73          * @param type
  74          * @return an accessor
  75          * @throws AccessorConstructionException
  76          */
  77         @SuppressWarnings("unchecked")
  78         public static <T extends Accessor> T getAccessor(RandomAccessBinary binary, Datatype type) throws AccessorConstructionException {
  79                 return (T) BinaryObject.createAccessor(binary, type, AccessorParams.DEFAULT);
  80         }
  81
  82         /**
  83          * Open an accessor to byte data.
  84          *
  85          * @param binary
  86          * @param type
  87          * @return an accessor
  88          * @throws AccessorConstructionException
  89          */
  90         @SuppressWarnings("unchecked")
  91         public static <T extends Accessor> T getAccessor(byte[] binary, Datatype type) throws AccessorConstructionException {
  92                 RandomAccessBinary rab = new BinaryMemory( ByteBuffer.wrap(binary) );
  93                 return (T) BinaryObject.createAccessor(rab, type, AccessorParams.DEFAULT);
  94         }
  95
  96         /**
  97          * Open an accessor to a Java Object.
  98          * <p>
  99          * Accessor is disposed by leaving it to garbage collector.
 100          * <p>
 101          * Do not modify the object outside the accessor as long as you use the accessor.
 102          * Exterioir modifications will mix up listening the mechanism.
 103          * Also, do not create more than one accessor to one Object.
 104          * <p>
 105          * You must provide mutual exclusion locking mechanism to the whole Object Model
 106          * in AccessorParams, if you intend to use the accessors in multi-thread environment.
 107          *
 108          * @since 0.5
 109          * @param binding
 110          * @param value
 111          * @return accessor
 112          * @throws AccessorConstructionException
 113          */
 114         @SuppressWarnings("unchecked")
 115         public static <T extends Accessor> T getAccessor(Binding binding, Object value, AccessorParams params)
 116         throws AccessorConstructionException {
 117                 return (T) JavaObject.createAccessor(null, binding, value, params);
 118         }
 119
 120         /**
 121          * Open an accessor to a Java Object.
 122          * <p>
 123          * Accessor is disposed by leaving it to garbage collector.
 124          * <p>
 125          * Do not modify the object outside the accessor as long as you use the accessor.
 126          * Exterioir modifications will mix up listening the mechanism.
 127          * Also, do not create more than one accessor to one Object.
 128          * <p>
 129          * The accessor is not multi-thread accessible. If you intend to use it in
 130          * concurrent multi-thread environment, use the other method where you can
 131          * pass lock objects in AccessorParams.
 132          *
 133          * @since 0.5
 134          * @param binding
 135          * @param value
 136          * @return accessor
 137          * @throws AccessorConstructionException
 138          */
 139         @SuppressWarnings("unchecked")
 140         public static <T extends Accessor> T getAccessor(Binding binding, Object value)
 141         throws AccessorConstructionException {
 142                 return (T) JavaObject.createAccessor(null, binding, value, AccessorParams.DEFAULT);
 143         }
 144
 145         /**
 146          * Open an accessor to a Varint Object.
 147          * <p>
 148          * Accessor is disposed by leaving it to garbage collector.
 149          * <p>
 150          * Do not modify the object outside the accessor as long as you use the accessor.
 151          * Exterioir modifications will mix up listening the mechanism.
 152          * Also, do not create more than one accessor to one Object.
 153          * <p>
 154          * The accessor is not multi-thread accessible. If you intend to use it in
 155          * concurrent multi-thread environment, use the other method where you can
 156          * pass lock objects in AccessorParams.
 157          *
 158          * @since 0.5
 159          * @param variant
 160          * @return accessor
 161          * @throws AccessorConstructionException
 162          */
 163         @SuppressWarnings("unchecked")
 164         public static <T extends Accessor> T getAccessor(Variant variant)
 165         throws AccessorConstructionException {
 166                 return (T) JavaObject.createAccessor(null, variant.getBinding(), variant.getValue(), AccessorParams.DEFAULT);
 167         }
 168
 169         /**
 170          * Open an accessor to a Varint Object.
 171          * <p>
 172          * Accessor is disposed by leaving it to garbage collector.
 173          * <p>
 174          * Do not modify the object outside the accessor as long as you use the accessor.
 175          * Exterioir modifications will mix up listening the mechanism.
 176          * Also, do not create more than one accessor to one Object.
 177          * <p>
 178          * The accessor is not multi-thread accessible. If you intend to use it in
 179          * concurrent multi-thread environment, use the other method where you can
 180          * pass lock objects in AccessorParams.
 181          *
 182          * @since 0.5
 183          * @param binding
 184          * @param ref child reference
 185          * @return accessor
 186          * @throws AccessorConstructionException
 187          */
 188         @SuppressWarnings("unchecked")
 189         public static <T extends Accessor> T getAccessor(Variant variant, ChildReference ref)
 190         throws AccessorConstructionException {
 191                 Accessor a = getAccessor( variant );
 192                 return a.getComponent( ref );
 193         }
 194
 195         /**
 196          * Open Accessor to a Java Object. This version reads the type using reflection.
 197          * <p>
 198          * Accessor is disposed by leaving it to garbage collector.
 199          * <p>
 200          * Do not modify the object outside the accessor as long as you use the accessor.
 201          * Exterioir modifications will mix up listening the mechanism.
 202          * Also, do not create more than one accessor to one Object.
 203          * <p>
 204          * The accessor is not multi-thread accessible. If you intend to use it in
 205          * concurrent multi-thread environment, use the other method where you can
 206          * pass lock objects in AccessorParams.
 207          *
 208          * @since 0.5
 209          * @param value
 210          * @return accessor
 211          * @throws AccessorConstructionException
 212          */
 213         @SuppressWarnings("unchecked")
 214         public static <T extends Accessor> T getAccessor(Object value)
 215         throws AccessorConstructionException {
 216                 try {
 217                         Binding binding = Bindings.getBinding(value.getClass());
 218                         return (T) JavaObject.createAccessor(null, binding, value, AccessorParams.DEFAULT);
 219                 } catch (BindingConstructionException e) {
 220                         throw new AccessorConstructionException(e);
 221                 }
 222         }
 223
 224         /**
 225          * Open an accessor to a binary file (.dbb). The file is always a variant.
 226          * The accessor must be closed by invoking {@link FileAccessor#close()} at
 227          * root or any sub-accessor.
 228          * <p>
 229          * To share accessors of the same file use {@link FileLibrary} utility.
 230          *
 231          * @since 0.5
 232          * @param file
 233          * @return file accessor
 234          * @throws AccessorConstructionException
 235          */
 236         public static FileVariantAccessor openAccessor(File file) throws AccessorConstructionException {
 237                 try {
 238                         BinaryFile bf = new BinaryFile(file);
 239                         FileVariantAccessor result = (FileVariantAccessor) BinaryObject.createAccessor(bf, Datatypes.VARIANT, AccessorParams.DEFAULT);
 240                         return result;
 241                 } catch (IOException e) {
 242                         throw new AccessorConstructionException(e);
 243                 }
 244         }
 245
 246         /**
 247          * Open a stream file (.stm). Stream file is an array of elements, with no
 248          * header. Element size is constant.
 249          * <p>
 250          * To create an empty stream file, just create an empty file.
 251          *
 252          * @param file
 253          * @param type expected array type
 254          * @return accessor
 255          * @throws AccessorConstructionException
 256          */
 257         public static FileArrayAccessor openStream(File file, ArrayType type) throws AccessorConstructionException {
 258                 return openStream(file, type, "rw");
 259         }
 260
 261         /**
 262          * Open a stream file (.stm). Stream file is an array of elements, with no
 263          * header. Element size is constant.
 264          * <p>
 265          * To create an empty stream file, just create an empty file.
 266          *
 267          * @param file
 268          * @param type expected array type
 269          * @param mode Mode "r" or "rw"
 270          * @return accessor
 271          * @throws AccessorConstructionException
 272          */
 273         public static FileArrayAccessor openStream(File file, ArrayType type, String mode) throws AccessorConstructionException {
 274                 return openStream(file, type, mode, null);
 275         }
 276
 277         /**
 278          * Open a stream file (.stm). Stream file is an array of elements, with no
 279          * header. Element size is constant.
 280          * <p>
 281          * To create an empty stream file, just create an empty file.
 282          *
 283          * @param file
 284          * @param type expected array type
 285          * @param mode Mode "r" or "rw"
 286          * @param index accessor to long array that keeps the index of the variable width stream
 287          * @return accessor
 288          * @throws AccessorConstructionException
 289          */
 290         public static FileArrayAccessor openStream(File file, ArrayType type, String mode, ArrayAccessor index) throws AccessorConstructionException {
 291                 try {
 292                         BinaryFile bf = new BinaryFile(file, mode);
 293                         Blob blob = new Blob(bf);
 294                         Binding b = Bindings.getBinding(type.componentType);
 295                         Serializer s = Bindings.getSerializer(b);
 296                         if ( s.getConstantSize() != null ) {
 297                                 return new BinaryStreamArray(null, blob, type, AccessorParams.DEFAULT);
 298                         } else {
 299                                 if ( index == null ) {
 300                                         return new BinaryArray(null, blob, type, AccessorParams.DEFAULT);
 301                                 } else {
 302                                         return new BinaryVariableWidthStreamArray(null, blob, type, AccessorParams.DEFAULT, index);
 303                                 }
 304                         }
 305                 } catch (IOException e) {
 306                         throw new AccessorConstructionException(e);
 307                 } catch (AccessorException e) {
 308                         throw new AccessorConstructionException(e);
 309                 } catch (SerializerConstructionException e) {
 310                         throw new AccessorConstructionException(e);
 311                 }
 312         }
 313
 314         /**
 315          * Create a new binary file with an empty value and open an accessor.
 316          * If file already exists, it is overwritten.
 317          * It is recommended that the file extension is .dbb (Databoard Binary)
 318          * <p>
 319          * The caller must close the file with {@link FileAccessor#close()}.
 320          *
 321          * @since 0.5
 322          * @param file
 323          * @return an accessor to the root variant node
 324          */
 325         public static FileVariantAccessor createFile(File file)
 326         throws AccessorConstructionException {
 327                 try {
 328                         file.createNewFile();
 329                         BinaryFile bf = new BinaryFile(file);
 330                         FileVariantAccessor result = (FileVariantAccessor) BinaryObject.createAccessor(bf, Datatypes.VARIANT, AccessorParams.DEFAULT);
 331
 332                         // Write initial value
 333                         try {
 334                                 Binding vb = Bindings.getBinding(void.class);
 335                                 Object vv = vb.createDefault();
 336                                 result.setContentValue(vb, vv);
 337                         } catch (AccessorException e) {
 338                                 // Close file
 339                                 try { result.close(); } catch (AccessorException e1) {}
 340                                 // Rethrow exception
 341                                 throw new AccessorConstructionException(e);
 342                         } catch (BindingConstructionException e) {
 343                                 // Close file
 344                                 try { result.close(); } catch (AccessorException e1) {}
 345                                 // Rethrow exception
 346                                 throw new AccessorConstructionException(e);
 347                         } catch (BindingException e) {
 348                                 // Close file
 349                                 try { result.close(); } catch (AccessorException e1) {}
 350                                 // Rethrow exception
 351                                 throw new AccessorConstructionException(e);
 352                         }
 353
 354                         return result;
 355                 } catch (IOException e) {
 356                         throw new AccessorConstructionException(e);
 357                 }
 358         }
 359
 360         /**
 361          * Create a binary file (.dbb) and open an accessor. The file is always a variant.
 362          * <p>
 363          * File is closed with {@link FileAccessor#close()} at root or any
 364          * sub-accessor.
 365          * <p>
 366          * To share accessors of the same file use {@link FileLibrary} utility.
 367          *
 368          * @param <T>
 369          * @param file
 370          * @param type
 371          * @return an accessor to the value node
 372          * @throws AccessorConstructionException
 373          */
 374         @SuppressWarnings("unchecked")
 375         public static <T extends FileAccessor> T createFile(File file, Datatype type) throws AccessorConstructionException
 376         {
 377                 boolean existed;
 378                 BinaryFile bf;
 379                 try {
 380                         existed = file.createNewFile();
 381                         bf = new BinaryFile(file);
 382                 } catch (IOException e1) {
 383                         throw new AccessorConstructionException(e1);
 384                 }
 385
 386                 try {
 387                         FileVariantAccessor result = (FileVariantAccessor) BinaryObject.createAccessor(bf, Datatypes.VARIANT, AccessorParams.DEFAULT);
 388                         Binding binding = Bindings.getMutableBinding(type);
 389                         Object value = binding.createDefault();
 390                         result.setContentValue(binding, value);
 391                         return (T) result.getContentAccessor();
 392                 } catch (BindingException e) {
 393                         if (!existed) file.delete();
 394                         throw new AccessorConstructionException(e);
 395                 } catch (AccessorException e) {
 396                         if (!existed) file.delete();
 397                         throw new AccessorConstructionException(e);
 398                 }
 399         }
 400
 401         /**
 402          * Open a Map(Variant, Variant) accessor to a directory.
 403          * Map entries are binary files (.dbb), and the file name is the key with the following encoding:
 404          *
 405          *  Filenames have the following encoding:
 406          *    S<string>.dbb   String types
 407          *                        Control characters " : < > | ? * \ / % [0..31] [128..] are escaped as %<hex><hex>
 408          *                        " "-space is _
 409          *    I<integer>.dbb  Integer types
 410          *    L<long>.dbb     Long types
 411          *    H<hex>.dbb      All other cases the value as binary
 412          *
 413          * The caller must close (FolderMap#close()) the accessor after usage.
 414          * This releases file handles and a directory polling thread.
 415          *
 416          * FolderMap is not concurrent-use-safe. Its files are not either.
 417          * The user must ensure that the files are not used concurrently from
 418          * different threads.
 419          *
 420          * @param directory
 421          * @return MapAccessor
 422          */
 423         public static DirectoryMap openDirectory(File directory) {
 424                 return new DirectoryMap(directory);
 425         }
 426
 427         /**
 428          * Get an executor for current thread
 429          *
 430          * @return executor
 431          */
 432         public static Executor getCurrentThread() {
 433                 return Accessors.getCurrentThread();
 434         }
 435
 436         static Executor CURRENT_THREAD = new Executor() {
 437                 @Override
 438                 public void execute(Runnable command) {
 439                         command.run();
 440                 }
 441         };
 442
 443 }
 444