1 /****************************************************************
2 * Licensed to the Apache Software Foundation (ASF) under one *
3 * or more contributor license agreements. See the NOTICE file *
4 * distributed with this work for additional information *
5 * regarding copyright ownership. The ASF licenses this file *
6 * to you under the Apache License, Version 2.0 (the *
7 * "License"); you may not use this file except in compliance *
8 * with the License. You may obtain a copy of the License at *
9 * *
10 * http://www.apache.org/licenses/LICENSE-2.0 *
11 * *
12 * Unless required by applicable law or agreed to in writing, *
13 * software distributed under the License is distributed on an *
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
15 * KIND, either express or implied. See the License for the *
16 * specific language governing permissions and limitations *
17 * under the License. *
18 ****************************************************************/
19 package org.apache.jsieve.mailet;
20
21 import java.io.IOException;
22 import java.io.InputStream;
23
24 /**
25 * <p>Experimental API locates resources.
26 * Used to load Sieve scripts. The base for relative URLs
27 * should be taken to be the root of the James configuration.
28 * </p><p>
29 * Required schemas:
30 * </p>
31 * <ul>
32 * <li><strong>User sieve scripts</strong> - the relative URL scheme
33 * <code>//<em>user</em>@<em>host</em>/<em>sieve</em> will be used to
34 * obtain the script
35 * </ul>
36 * <p>
37 * The advantage of using <code>URI</code>s
38 * and verbs (for example <code>GET</code>, <code>POST</code>)
39 * are their uniformity. The same API can be used to interface radically
40 * different resource types and protocols. This allows concise, minimal,
41 * powerful APIs to be created. Their simplicity is easy to preserved
42 * across versions.
43 * </p><p>
44 * The disadvantage is that this free decouple means that there is
45 * no gaurantee that the implementations decoupled by this interface
46 * actually support the same scheme. Issues will be caught only
47 * at deployment and not at compile time.
48 * This places a larger burden on the deployer.
49 * </p><p>
50 * Either an understanding or a consistent URL mapping scheme may be
51 * required. For example, <code>//john.smith@localhost/sieve</code>
52 * may need to be resolved to <code>../apps/james/var/sieve/john.smith@localhost.sieve</code>
53 * when using the file system to store scripts. Note that names <strong>MUST</strong>
54 * be normalised before resolving on a file system.
55 * </p>
56 */
57 public interface ResourceLocator {
58
59 /**
60 * GET verb locates and loads a resource.
61 * @param uri identifies the Sieve script
62 * @return not null
63 * @throws IOException when the resource cannot be located
64 */
65 public InputStream get(String uri) throws IOException;
66 }