View Javadoc
1   /*
2    * Copyright (C) 2005-2015 Schlichtherle IT Services.
3    * All rights reserved. Use is subject to license terms.
4    */
5   package net.java.truevfs.kernel.spec;
6   
7   import javax.annotation.CheckForNull;
8   import net.java.truecommons.shed.ImplementationsShouldExtend;
9   
10  /**
11   * Defines common properties of any file system.
12   * <p>
13   * Implementations should be safe for multi-threaded access.
14   *
15   * @see    FsController
16   * @see    FsManager
17   * @author Christian Schlichtherle
18   */
19  @ImplementationsShouldExtend(FsAbstractModel.class)
20  public interface FsModel {
21  
22      /**
23       * Returns the mount point of the file system.
24       * The mount point may be used to construct error messages or to locate
25       * and access file system meta data which is stored outside the file system,
26       * e.g. passwords for RAES encrypted ZIP files.
27       *
28       * @return The mount point of the file system.
29       */
30      FsMountPoint getMountPoint();
31  
32      /**
33       * Returns the parent file system model or {@code null} if and only if the
34       * file system is not federated, i.e. if it's not a member of a parent file
35       * system.
36       *
37       * @return The nullable parent file system model.
38       */
39      @CheckForNull FsModel getParent();
40  
41      /**
42       * Returns {@code true} if and only if some state associated with the
43       * federated file system has been modified so that the
44       * corresponding {@link FsController} must not get discarded until
45       * the next call to {@link FsController#sync sync}.
46       * <p>
47       * An implementation may always return {@code false} if the associated
48       * file system controller is stateless.
49       *
50       * @return {@code true} if and only if some state associated with the
51       *         federated file system has been modified so that the
52       *         corresponding {@link FsController} must not get discarded until
53       *         the next {@link FsController#sync sync}.
54       */
55      boolean isMounted();
56  
57      /**
58       * Sets the value of the property {@link #isMounted() mounted}.
59       * Only file system controllers should call this method in order to
60       * register themselves for a call their {@link FsController#sync} method.
61       * <p>
62       * An implementation may ignore calls to this method if the associated
63       * file system controller is stateless.
64       *
65       * @param mounted the new value of this property.
66       */
67      void setMounted(boolean mounted);
68  
69      /**
70       * A factory for {@linkplain FsModel file system models}.
71       * <p>
72       * Implementations should be safe for multi-threaded access.
73       *
74       * @param  <Context> The type of the calling context.
75       * @since  TrueVFS 0.11
76       * @author Christian Schlichtherle
77       */
78      interface Factory<Context> {
79  
80          /**
81           * Returns a new file system model for the given mount point.
82           * This is a pure function without side effects.
83           * <p>
84           * When called, you may assert the following precondition:
85           * <pre>{@code
86           * assert null == parent
87           *         ? null == mountPoint.getParent()
88           *         : parent.getMountPoint().equals(mountPoint.getParent());
89           * }</pre>
90           *
91           * @param  context the calling context.
92           * @param  mountPoint the mount point of the file system.
93           * @param  parent the nullable parent file system model.
94           * @return A new file system model for the given mount point.
95           */
96          FsModel newModel(
97                  Context context,
98                  FsMountPoint mountPoint,
99                  @CheckForNull FsModel parent);
100     }
101 }