KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > osgi > service > datalocation > Location


1 /*******************************************************************************
2  * Copyright (c) 2004, 2006 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.osgi.service.datalocation;
12
13 import java.io.IOException JavaDoc;
14 import java.net.URL JavaDoc;
15
16 /**
17  * A Location represents a URL which may have a default value, may be read only, may
18  * or may not have a current value and may be cascaded on to a parent location.
19  * <p>
20  * This interface is not intended to be implemented by clients.
21  * </p>
22  *
23  * @since 3.0
24  */
25 public interface Location {
26
27     /**
28      * Constant which defines the filter string for acquiring the service which
29      * specifies the instance location.
30      *
31      * @since 3.2
32      */
33     public static final String JavaDoc INSTANCE_FILTER = "(&(objectClass=" + Location.class.getName() + ")(type=osgi.instance.area))"; //$NON-NLS-1$ //$NON-NLS-2$
34
35     /**
36      * Constant which defines the filter string for acquiring the service which
37      * specifies the install location.
38      *
39      * @since 3.2
40      */
41     public static final String JavaDoc INSTALL_FILTER = "(&(objectClass=" + Location.class.getName() + ")(type=osgi.install.area))"; //$NON-NLS-1$ //$NON-NLS-2$
42
43     /**
44      * Constant which defines the filter string for acquiring the service which
45      * specifies the configuration location.
46      *
47      * @since 3.2
48      */
49     public static final String JavaDoc CONFIGURATION_FILTER = "(&(objectClass=" + Location.class.getName() + ")(type=osgi.configuration.area))"; //$NON-NLS-1$ //$NON-NLS-2$
50
51     /**
52      * Constant which defines the filter string for acquiring the service which
53      * specifies the user location.
54      *
55      * @since 3.2
56      */
57     public static final String JavaDoc USER_FILTER = "(&(objectClass=" + Location.class.getName() + ")(type=osgi.user.area))"; //$NON-NLS-1$ //$NON-NLS-2$
58
59     /**
60      * Returns <code>true</code> if this location allows a default value to be assigned
61      * and <code>false</code> otherwise.
62      *
63      * @return whether or not this location can have a default value assigned
64      */
65     public boolean allowsDefault();
66
67     /**
68      * Returns the default value of this location if any. If no default is available then
69      * <code>null</code> is returned. Note that even locations which allow defaults may still
70      * return <code>null</code>.
71      *
72      * @return the default value for this location or <code>null</code>
73      */
74     public URL JavaDoc getDefault();
75
76     /**
77      * Returns the parent of this location or <code>null</code> if none is available.
78      *
79      * @return the parent of this location or <code>null</code>
80      */
81     public Location getParentLocation();
82
83     /**
84      * Returns the actual {@link URL} of this location. If the location's value has been set,
85      * that value is returned. If the value is not set and the location allows defaults,
86      * the value is set to the default and returned. In all other cases <code>null</code>
87      * is returned.
88      *
89      * @return the URL for this location or <code>null</code> if none
90      */
91     public URL JavaDoc getURL();
92
93     /**
94      * Returns <code>true</code> if this location has a value and <code>false</code>
95      * otherwise.
96      *
97      * @return boolean value indicating whether or not the value is set
98      */
99     public boolean isSet();
100
101     /**
102      * Returns <code>true</code> if this location represents a read only location and
103      * <code>false</code> otherwise. The read only character
104      * of a location is not in enforced in any way but rather expresses the intention of the
105      * location's creator.
106      *
107      * @return boolean value indicating whether the location is read only
108      */
109     public boolean isReadOnly();
110
111     /**
112      * Sets and optionally locks the location's value to the given {@link URL}. If the location
113      * already has a value an exception is thrown. If locking is requested and fails, <code>false</code>
114      * is returned and the {@link URL} of this location is not set.
115      *
116      * @param value the value of this location
117      * @param lock whether or not to lock this location
118      * @return whether or not the location was successfully set and, if requested, locked.
119      * @throws IllegalStateException if the location's value is already set
120      */
121     public boolean setURL(URL JavaDoc value, boolean lock) throws IllegalStateException JavaDoc;
122
123     /**
124      * Attempts to lock this location with a canonical locking mechanism and return
125      * <code>true</code> if the lock could be acquired. Not all locations can be
126      * locked.
127      * <p>
128      * Locking a location is advisory only. That is, it does not prevent other applications from
129      * modifying the same location
130      * </p>
131      * @return true if the lock could be acquired; otherwise false is returned
132      *
133      * @exception IOException if there was an unexpected problem while acquiring the lock
134      */
135     public boolean lock() throws IOException JavaDoc;
136
137     /**
138      * Releases the lock on this location. If the location is not already locked, no action
139      * is taken.
140      */
141     public void release();
142 }
143
Popular Tags