ResourceHandler.java
01 /*
02  * SPDX-License-Identifier: Apache-2.0
03  *
04  * Copyright 2008-2017 the original author or authors.
05  *
06  * Licensed under the Apache License, Version 2.0 (the "License");
07  * you may not use this file except in compliance with the License.
08  * You may obtain a copy of the License at
09  *
10  *     http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 package griffon.core.resources;
19 
20 import javax.annotation.Nonnull;
21 import javax.annotation.Nullable;
22 import java.io.InputStream;
23 import java.net.URL;
24 import java.util.List;
25 
26 /**
27  * Indicates a type that knows how to load resources from the classpath.
28  *
29  @author Andres Almiray
30  @since 2.0.0
31  */
32 public interface ResourceHandler {
33     /**
34      * Finds the resource with the given name.  A resource is some data
35      * (images, audio, text, etc) that can be accessed by class code in a way
36      * that is independent of the location of the code.
37      <p/>
38      <p> The name of a resource is a '<tt>/</tt>'-separated path name that
39      * identifies the resource.
40      *
41      @param name The resource name
42      @return <tt>URL</tt> object for reading the resource, or
43      *         <tt>null</tt> if the resource could not be found.
44      */
45     @Nullable
46     URL getResourceAsURL(@Nonnull String name);
47 
48     /**
49      * Returns an input stream for reading the specified resource.
50      *
51      @param name The resource name
52      @return An input stream for reading the resource, or <tt>null</tt>
53      *         if the resource could not be found
54      */
55     @Nullable
56     InputStream getResourceAsStream(@Nonnull String name);
57 
58     /**
59      * Finds all the resources with the given name. A resource is some data
60      * (images, audio, text, etc) that can be accessed by class code in a way
61      * that is independent of the location of the code.
62      <p/>
63      <p>The name of a resource is a <tt>/</tt>-separated path name that
64      * identifies the resource.
65      *
66      @param name The resource name
67      @return An java.util.List of {@link java.net.URL <tt>URL</tt>} objects for
68      *         the resource.  If no resources could  be found, the list
69      *         will be empty.  Resources that the class loader doesn't have
70      *         access to will not be in the list.
71      */
72     @Nullable
73     List<URL> getResources(@Nonnull String name);
74 
75     /**
76      * Returns the classloader used to resolve resources.
77      *
78      @return a classloader instance
79      */
80     @Nonnull
81     ClassLoader classloader();
82 }