001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041: package org.openide.util;
042:
043: import org.openide.filesystems.FileObject;
044: import org.openide.util.NbBundle;
045:
046: import java.net.InetAddress;
047: import java.net.MalformedURLException;
048: import java.net.URL;
049: import java.net.UnknownHostException;
050:
051: /** Maps internal NetBeans resources such as repository objects to URLs.
052: * The mapping is delegated to an HTTP server module, which registers to do
053: * the mapping. It is also responsible for actually serving the individual data objects
054: * from the Repository and resources from the system classpath.
055: * @author Petr Jiricka
056: * @deprecated The <code>httpserver</code> module should provide a replacement for this API if necessary.
057: */
058: public abstract class HttpServer {
059: /** regular server to be used */
060: private static HttpServer.Impl registeredServer = null;
061:
062: private HttpServer() {
063: }
064:
065: /** Returns a server implementation which is currently registered with the system.
066: * Server implementation obtained from Lookup has highest priority.
067: * 'Normal' registered server has priority over a default registered server.
068: * If no server has been registered, internal error is
069: */
070: private static HttpServer.Impl getServer()
071: throws UnknownHostException {
072: Object o = Lookup.getDefault().lookup(HttpServer.Impl.class);
073:
074: if (o != null) {
075: return (HttpServer.Impl) o;
076: }
077:
078: if (registeredServer != null) {
079: return registeredServer;
080: } else {
081: throw new UnknownHostException(NbBundle.getBundle(
082: HttpServer.class).getString(
083: "MSG_NoServerRegistered"));
084: }
085: }
086:
087: /** Register the system HTTP server.
088: * Typically this would be done in {@link org.openide.modules.ModuleInstall#installed}
089: * or {@link org.openide.modules.ModuleInstall#restored}.
090: * @param server the server to register
091: * @throws SecurityException if there was already one registered
092: * @deprecated As of 2.11 use Lookup instead of registering HTTP server
093: */
094: public static void registerServer(HttpServer.Impl server)
095: throws SecurityException {
096: if (registeredServer != null) {
097: throw new SecurityException(NbBundle.getBundle(
098: HttpServer.class).getString("SERVER_REGISTERED"));
099: }
100:
101: registeredServer = server;
102: }
103:
104: /** Deregister the system HTTP server.
105: * Typically this would be done in {@link org.openide.modules.ModuleInstall#uninstalled}.
106: * @param server the server to deregister
107: * @throws SecurityException if the specified server was not the installed one
108: * @deprecated As of 2.11 use Lookup instead of registering and derigistering HTTP server
109: */
110: public static void deregisterServer(HttpServer.Impl server)
111: throws SecurityException {
112: if (registeredServer == null) {
113: return; // [PENDING] maybe remove this test and let it throw sec exc --jglick
114: }
115:
116: if (registeredServer != server) {
117: throw new SecurityException(NbBundle.getBundle(
118: HttpServer.class).getString(
119: "SERVER_CANNOT_UNREGISTER"));
120: } else {
121: registeredServer = null;
122: }
123: }
124:
125: /** Map a file object to a URL.
126: * Should ensure that the file object is accessible via the given URL.
127: * @param fo the file object to represent
128: * @return a URL providing access to it
129: * @throws MalformedURLException for the usual reasons
130: * @throws UnknownHostException for the usual reasons, or if there is no registered server
131: * @deprecated Use {@link org.openide.filesystems.URLMapper} instead.
132: */
133: public static URL getRepositoryURL(FileObject fo)
134: throws MalformedURLException, UnknownHostException {
135: return getServer().getRepositoryURL(fo);
136: }
137:
138: /** Map the repository root to a URL.
139: * This URL should serve a page from which repository objects are accessible.
140: * This means that it should serve a package-oriented view of the Repository, corresponding
141: * to a merge of all files present in the root folders of visible file systems.
142: * @return a URL
143: * @throws MalformedURLException for the usual reasons
144: * @throws UnknownHostException for the usual reasons, or if there is no registered server
145: * @deprecated Assumes repository equals classpath.
146: */
147: public static URL getRepositoryRoot() throws MalformedURLException,
148: UnknownHostException {
149: return getServer().getRepositoryRoot();
150: }
151:
152: /** Map a resource path to a URL.
153: * Should ensure that the resource is accessible via the given URL.
154: * @param resourcePath path of the resource in classloader format (e.g. <code>/some/path/resources/icon32.gif</code>)
155: * @return a URL providing access to it
156: * @see ClassLoader#getResource(java.lang.String)
157: * @throws MalformedURLException for the usual reasons
158: * @throws UnknownHostException for the usual reasons, or if there is no registered server
159: * @deprecated Use {@link org.openide.filesystems.URLMapper} with a URL protocol <code>nbres</code>.
160: */
161: public static URL getResourceURL(String resourcePath)
162: throws MalformedURLException, UnknownHostException {
163: return getServer().getResourceURL(resourcePath);
164: }
165:
166: /** Get URL root for a resource from system classpath.
167: * @return the URL
168: * @throws MalformedURLException for the usual reasons
169: * @throws UnknownHostException for the usual reasons
170: * @see HttpServer#getResourceURL
171: * @deprecated Use {@link org.openide.filesystems.URLMapper} with a URL protocol <code>nbres</code>.
172: */
173: public static URL getResourceRoot() throws MalformedURLException,
174: UnknownHostException {
175: return getServer().getResourceRoot();
176: }
177:
178: /** Requests the server to allow access to it from a given IP address.
179: * This can be useful if a module wishes another machine to be able to access
180: * the server, such as a machine running a deployment server.
181: * The server may or may not grant access to the IP address, for example
182: * if the user does not wish to grant access to the IP address.
183: * @param addr address for which access is requested
184: * @return <code>true</code> if access has been granted
185: * @deprecated Should be replaced by an API in the <code>httpserver</code> module if still required.
186: */
187: public static boolean allowAccess(InetAddress addr)
188: throws UnknownHostException {
189: return getServer().allowAccess(addr);
190: }
191:
192: /** Implementation of the HTTP server.
193: * Must be implemented by classes which want to register as a server.
194: * Implementations are obtained using Lookup.
195: * <p>Such a server must be prepared to specially serve pages from
196: * within the IDE, i.e. the Repository and the system class
197: * loader. (It may also serve external pages, if desired.) It should
198: * have a system option specifying at least the port number (<em>by
199: * default, an unused port above 1000</em>), the host access
200: * restrictions (<em>by default, only <code>localhost</code></em>),
201: * and an toggle to disable it. It should provide URLs using the
202: * protocol <code>http</code> so as not to need to register a new protocol
203: * handler.
204: * @deprecated Useful only for {@link HttpServer} which is itself deprecated.
205: */
206: public interface Impl {
207: /** Get the URL for a file object.
208: * @param fo the file object
209: * @return the URL
210: * @throws MalformedURLException for the usual reasons
211: * @throws UnknownHostException for the usual reasons
212: * @see HttpServer#getRepositoryURL
213: */
214: public URL getRepositoryURL(FileObject fo)
215: throws MalformedURLException, UnknownHostException;
216:
217: /** Get the URL for the Repository. For this URL,
218: * the implementation should display a page containing a list of links to subdirectories (packages).
219: * @return the URL
220: * @throws MalformedURLException for the usual reasons
221: * @throws UnknownHostException for the usual reasons
222: * @see HttpServer#getRepositoryRoot
223: */
224: public URL getRepositoryRoot() throws MalformedURLException,
225: UnknownHostException;
226:
227: /** Get the URL for a resource from system classpath. The URL must comply to java naming conventions,
228: * i.e. the URL must end with a fully qualified resource name.
229: * @param resourcePath the resource path
230: * @return the URL
231: * @throws MalformedURLException for the usual reasons
232: * @throws UnknownHostException for the usual reasons
233: * @see HttpServer#getResourceURL
234: */
235: public URL getResourceURL(String resourcePath)
236: throws MalformedURLException, UnknownHostException;
237:
238: /** Get URL root for a resource from system classpath.
239: * @return the URL
240: * @throws MalformedURLException for the usual reasons
241: * @throws UnknownHostException for the usual reasons
242: * @see HttpServer#getResourceURL
243: */
244: public URL getResourceRoot() throws MalformedURLException,
245: UnknownHostException;
246:
247: /** Requests the server to allow access to it from a given IP address.
248: * This can be useful if a module wishes another machine to be able to access
249: * the server, such as a machine running a deployment server.
250: * The server may or may not grant access to the IP address, for example
251: * if the user does not wish to grant access to the IP address.
252: * @param addr address for which access is requested
253: * @return <code>true</code> if access has been granted
254: */
255: public boolean allowAccess(InetAddress addr)
256: throws UnknownHostException;
257: }
258: }
|