KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > net > proxy > IProxyService


1 /*******************************************************************************
2  * Copyright (c) 2007 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.core.net.proxy;
12
13 import org.eclipse.core.runtime.CoreException;
14
15 /**
16  * Manages the proxy data and related information. The proxy service is registered as
17  * an OSGi service. Clients can obtain an instance of the service from their bundle context
18  * or from a service tracker.
19  * <p>
20  * This interface is not intended to be implemented by clients.
21  * @since 1.0
22  */
23 public interface IProxyService {
24     
25     /**
26      * Set whether proxy support should be enabled. The current proxy settings are
27      * still kept so clients should check the enablement using {@link #isProxiesEnabled()}
28      * before calling the {@link #getProxyData()} or {@link #getProxyData(String)} method.
29      * However, the {@link #getProxyDataForHost(String)} and {@link #getProxyDataForHost(String, String)}
30      * method will check the enablement and only return data if the service is enabled.
31      * @param enabled whether proxy support should be enabled
32      */
33     void setProxiesEnabled(boolean enabled);
34     
35     /**
36      * Return whether proxy support should be enabled. When disabled, all connections
37      * will be direct.
38      * @return whether proxy support should be enabled
39      */
40     boolean isProxiesEnabled();
41     
42     /**
43      * Return the list of know proxy types and their settings.
44      * Some of the returned proxy types may not be enabled (i.e,
45      * their hosts may be <code>null</code>.
46      * @return the list of know proxy types and their settings
47      */
48     IProxyData[] getProxyData();
49     
50     /**
51      * Return the list of known proxy types and their settings for the
52      * given host. If proxies are disabled
53      * or if the host matches any entries in the non-proxied
54      * hosts lists or if a matching proxy type has no data, then
55      * an empty array is returned.
56      * @param host the host for which a connection is desired
57      * @return the list of known proxy types and their settings for the
58      * given host
59      */
60     IProxyData[] getProxyDataForHost(String JavaDoc host);
61     
62     /**
63      * Return the proxy data for the proxy of the given type
64      * or <code>null</code> if the proxy type is not known by this
65      * service.
66      * @param type the proxy type
67      * @return the proxy data for the proxy of the given type
68      * or <code>null</code>
69      * @see IProxyData#HTTP_PROXY_TYPE
70      * @see IProxyData#HTTPS_PROXY_TYPE
71      * @see IProxyData#SOCKS_PROXY_TYPE
72      */
73     IProxyData getProxyData(String JavaDoc type);
74     
75     /**
76      * Return the proxy data for the proxy of the given type
77      * or <code>null</code> if the proxy type is not known by this
78      * service, the proxy data is empty for that type or the
79      * host is in the non-proxied host list.
80      * @param host the host for which a connection is desired
81      * @param type the proxy type
82      * @return the proxy data for the proxy of the given type
83      * or <code>null</code>
84      * @see IProxyData#HTTP_PROXY_TYPE
85      * @see IProxyData#HTTPS_PROXY_TYPE
86      * @see IProxyData#SOCKS_PROXY_TYPE
87      */
88     IProxyData getProxyDataForHost(String JavaDoc host, String JavaDoc type);
89     
90     /**
91      * Set the information associated with known proxy types.
92      * If an unknown type is provided, it will be ignored. Any
93      * known types that are not present in the list of the provided
94      * proxy data will be unaffected.
95      * @param proxies the proxy data whose information is to be set.
96      * @throws CoreException if the proxy could not be set
97      */
98     void setProxyData(IProxyData[] proxies) throws CoreException;
99     
100     /**
101      * Return the list of hosts for which non proxy should be used.
102      * The values returned from this method should only be used for displaying
103      * the non-proxed hosts list. Clients that which to make a connection and need
104      * to determine whether to use a proxy or not shoudl call either {@link #getProxyDataForHost(String)}
105      * or {@link #getProxyDataForHost(String, String)}.
106      * @return the list of hosts for which non proxy should be used.
107      * @see #getProxyDataForHost(String)
108      * @see #getProxyDataForHost(String, String)
109      */
110     String JavaDoc[] getNonProxiedHosts();
111     
112     /**
113      * Set the list of hosts for which non proxy should be used.
114      * @param hosts the list of hosts for which non proxy should be used.
115      * @throws CoreException if the non-proxied host list could not be set
116      */
117     void setNonProxiedHosts(String JavaDoc[] hosts) throws CoreException;
118     
119     /**
120      * Register a listener that will be notified when proxy related
121      * information changes. Adding a listener that is already registered
122      * has no effect.
123      * @param listener a change listener
124      */
125     void addProxyChangeListener(IProxyChangeListener listener);
126     
127     /**
128      * Remove a listener. Removing a listener that is not registered
129      * has no effect.
130      * @param listener a change listener
131      */
132     void removeProxyChangeListener(IProxyChangeListener listener);
133
134 }
135
Popular Tags