1 /* Copyright 2002-2020 CS GROUP
2 * Licensed to CS GROUP (CS) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * CS licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.orekit.data;
18
19 import java.util.regex.Pattern;
20
21 import org.orekit.annotation.DefaultDataContext;
22
23 /** Interface for providing data files to {@link DataLoader file loaders}.
24 * <p>
25 * This interface defines a generic way to explore some collection holding
26 * data files and load some of them. The collection may be a list of resources
27 * in the classpath, a directories tree in filesystem, a zip or jar archive,
28 * a database, a connexion to a remote server ...
29 * </p>
30 * <p>
31 * The proper way to use this interface is to configure one or more
32 * implementations and register them in the {@link DataProvidersManager data
33 * providers manager singleton}, or to let this manager use its default
34 * configuration. Once registered, they will be used automatically whenever
35 * some data needs to be loaded. This allow high level applications developers
36 * to customize Orekit data loading mechanism and get a tighter integration of
37 * the library within their application.
38 * </p>
39 * @see DataLoader
40 * @see DataProvidersManager
41 * @author Luc Maisonobe
42 */
43 public interface DataProvider {
44
45 /** Pattern for name of zip/jar archives. */
46 Pattern ZIP_ARCHIVE_PATTERN = Pattern.compile("(.*)(?:(?:\\.zip)|(?:\\.jar))$");
47
48 /** Feed a data file loader by browsing the data collection.
49 * <p>
50 * The method crawls all files referenced in the instance (for example
51 * all files in a directories tree) and for each file supported by the
52 * file loader it asks the file loader to load it.
53 * </p>
54 * <p>
55 * If the method completes without exception, then the data loader
56 * is considered to have been fed successfully and the top level
57 * {@link DataProvidersManager data providers manager} will return
58 * immediately without attempting to use the next configured providers.
59 * </p>
60 * <p>
61 * If the method completes abruptly with an exception, then the top level
62 * {@link DataProvidersManager data providers manager} will try to use
63 * the next configured providers, in case another one can feed the
64 * {@link DataLoader data loader}.
65 * </p>
66 * @param supported pattern for file names supported by the visitor
67 * @param visitor data file visitor to use
68 * @return true if some data has been loaded
69 * @deprecated Use {@link #feed(Pattern, DataLoader, DataProvidersManager)} instead
70 * which allows specifying the {@link DataProvidersManager} to use for filtering
71 * resources. This method uses the default instance:
72 * {@link DataProvidersManager#getInstance()}.
73 */
74 @Deprecated
75 @DefaultDataContext
76 boolean feed(Pattern supported, DataLoader visitor);
77
78 /** Feed a data file loader by browsing the data collection.
79 * <p>
80 * The method crawls all files referenced in the instance (for example
81 * all files in a directories tree) and for each file supported by the
82 * file loader it asks the file loader to load it.
83 * </p>
84 * <p>
85 * If the method completes without exception, then the data loader
86 * is considered to have been fed successfully and the top level
87 * {@link DataProvidersManager data providers manager} will return
88 * immediately without attempting to use the next configured providers.
89 * </p>
90 * <p>
91 * If the method completes abruptly with an exception, then the top level
92 * {@link DataProvidersManager data providers manager} will try to use
93 * the next configured providers, in case another one can feed the
94 * {@link DataLoader data loader}.
95 * </p>
96 *
97 * <p> The default implementation will be removed in 11.0. It calls {@link
98 * #feed(Pattern, DataLoader)}.
99 *
100 * @param supported pattern for file names supported by the visitor
101 * @param visitor data file visitor to use
102 * @param manager with the filters to apply to the resources.
103 * @return true if some data has been loaded
104 */
105 default boolean feed(final Pattern supported,
106 final DataLoader visitor,
107 final DataProvidersManager manager) {
108 return feed(supported, visitor);
109 }
110
111 }