View Javadoc

1   /*
2    * ModeShape (http://www.modeshape.org)
3    * See the COPYRIGHT.txt file distributed with this work for information
4    * regarding copyright ownership.  Some portions may be licensed
5    * to Red Hat, Inc. under one or more contributor license agreements.
6    * See the AUTHORS.txt file in the distribution for a full listing of 
7    * individual contributors.
8    *
9    * ModeShape is free software. Unless otherwise indicated, all code in ModeShape
10   * is licensed to you under the terms of the GNU Lesser General Public License as
11   * published by the Free Software Foundation; either version 2.1 of
12   * the License, or (at your option) any later version.
13   * 
14   * ModeShape is distributed in the hope that it will be useful,
15   * but WITHOUT ANY WARRANTY; without even the implied warranty of
16   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17   * Lesser General Public License for more details.
18   *
19   * You should have received a copy of the GNU Lesser General Public
20   * License along with this software; if not, write to the Free
21   * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
22   * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
23   */
24  package org.modeshape.connector.filesystem;
25  
26  import java.io.File;
27  import java.io.Serializable;
28  import java.util.Collection;
29  import java.util.Map;
30  import java.util.Set;
31  import net.jcip.annotations.Immutable;
32  import org.modeshape.graph.ExecutionContext;
33  import org.modeshape.graph.JcrLexicon;
34  import org.modeshape.graph.Location;
35  import org.modeshape.graph.connector.RepositorySourceException;
36  import org.modeshape.graph.property.Name;
37  import org.modeshape.graph.property.Property;
38  
39  /**
40   * A simple interface that allows an implementer to define additional properties for "nt:folder", "nt:file", and "nt:resource"
41   * nodes created by the file system connector.
42   * <p>
43   * To use, supply the implementation to a {@link FileSystemSource} object (or register the factory in a subclass of
44   * FileSystemSource). Implementations should be immutable because they are shared between all the connections.
45   * </p>
46   */
47  @Immutable
48  public interface CustomPropertiesFactory extends Serializable {
49  
50      /**
51       * Construct the custom properties that should be created for the supplied directory that is to be treated as an "nt:folder".
52       * The resulting properties should not include the standard {@link JcrLexicon#PRIMARY_TYPE} or {@link JcrLexicon#CREATED}
53       * properties, which are set automatically and will override any returned Property with the same name.
54       * 
55       * @param context the execution context; never null
56       * @param location the Location of the node, which always contains a {@link Location#getPath() path}; never null
57       * @param directory the file system object; never null and {@link File#isDirectory()} will always return true
58       * @return the custom properties; never null but possibly empty
59       */
60      Collection<Property> getDirectoryProperties( ExecutionContext context,
61                                                   Location location,
62                                                   File directory );
63  
64      /**
65       * Construct the custom properties that should be created for the supplied file that is to be treated as an "nt:resource",
66       * which is the node that contains the content-oriented properties and that is a child of a "nt:file" node. The resulting
67       * properties should not include the standard {@link JcrLexicon#PRIMARY_TYPE}, {@link JcrLexicon#LAST_MODIFIED}, or
68       * {@link JcrLexicon#DATA} properties, which are set automatically and will override any returned Property with the same name.
69       * 
70       * @param context the execution context; never null
71       * @param location the Location of the node, which always contains a {@link Location#getPath() path}; never null
72       * @param file the file system object; never null and {@link File#isFile()} will always return true
73       * @param mimeType the mime type for the file, as determined by the {@link ExecutionContext#getMimeTypeDetector() MIME type
74       *        detector}, or null if the MIME type could not be determined
75       * @return the custom properties; never null but possibly empty
76       */
77      Collection<Property> getResourceProperties( ExecutionContext context,
78                                                  Location location,
79                                                  File file,
80                                                  String mimeType );
81  
82      /**
83       * Construct the custom properties that should be created for the supplied file that is to be treated as an "nt:file". The
84       * resulting properties should not include the standard {@link JcrLexicon#PRIMARY_TYPE} or {@link JcrLexicon#CREATED}
85       * properties, which are set automatically and will override any returned Property with the same name.
86       * <p>
87       * Although the connector does not automatically determine the MIME type for the "nt:file" nodes, an implementation can
88       * determine the MIME type by using the context's {@link ExecutionContext#getMimeTypeDetector() MIME type detector}. Note,
89       * however, that this may be an expensive operation, so it should be used only when needed.
90       * </p>
91       * 
92       * @param context the execution context; never null
93       * @param location the Location of the node, which always contains a {@link Location#getPath() path}; never null
94       * @param file the file system object; never null and {@link File#isFile()} will always return true
95       * @return the custom properties; never null but possibly empty
96       */
97      Collection<Property> getFileProperties( ExecutionContext context,
98                                              Location location,
99                                              File file );
100 
101     /**
102      * Record the supplied properties as being set on the designated "nt:folder" node.
103      * 
104      * @param context the execution context; never null
105      * @param sourceName the name of the repository source; never null
106      * @param location the Location of the node, which always contains a {@link Location#getPath() path}; never null
107      * @param file the file system object; never null, and both {@link File#exists()} and {@link File#isDirectory()} will always
108      *        return true
109      * @param properties the properties that are to be set
110      * @return the names of the properties that were created, or an empty or null set if no properties were created on the file
111      * @throws RepositorySourceException if any properties are invalid or cannot be set on these nodes
112      */
113     Set<Name> recordDirectoryProperties( ExecutionContext context,
114                                          String sourceName,
115                                          Location location,
116                                          File file,
117                                          Map<Name, Property> properties ) throws RepositorySourceException;
118 
119     /**
120      * Record the supplied properties as being set on the designated "nt:file" node.
121      * 
122      * @param context the execution context; never null
123      * @param sourceName the name of the repository source; never null
124      * @param location the Location of the node, which always contains a {@link Location#getPath() path}; never null
125      * @param file the file system object; never null, and both {@link File#exists()} and {@link File#isFile()} will always return
126      *        true
127      * @param properties the properties that are to be set
128      * @return the names of the properties that were created, or an empty or null set if no properties were created on the file
129      * @throws RepositorySourceException if any properties are invalid or cannot be set on these nodes
130      */
131     Set<Name> recordFileProperties( ExecutionContext context,
132                                     String sourceName,
133                                     Location location,
134                                     File file,
135                                     Map<Name, Property> properties ) throws RepositorySourceException;
136 
137     /**
138      * Record the supplied properties as being set on the designated "nt:resource" node.
139      * 
140      * @param context the execution context; never null
141      * @param sourceName the name of the repository source; never null
142      * @param location the Location of the node, which always contains a {@link Location#getPath() path}; never null
143      * @param file the file system object; never null, and both {@link File#exists()} and {@link File#isFile()} will always return
144      *        true
145      * @param properties the properties that are to be set
146      * @return the names of the properties that were created, or an empty or null set if no properties were created on the file
147      * @throws RepositorySourceException if any properties are invalid or cannot be set on these nodes
148      */
149     Set<Name> recordResourceProperties( ExecutionContext context,
150                                         String sourceName,
151                                         Location location,
152                                         File file,
153                                         Map<Name, Property> properties ) throws RepositorySourceException;
154 
155 }