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 }