KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > ungoverned > oscar > BundleArchive


1 /*
2  * Oscar - An implementation of the OSGi framework.
3  * Copyright (c) 2004, Richard S. Hall
4  * All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions
8  * are met:
9  *
10  * * Redistributions of source code must retain the above copyright
11  * notice, this list of conditions and the following disclaimer.
12  * * Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in
14  * the documentation and/or other materials provided with the
15  * distribution.
16  * * Neither the name of the ungoverned.org nor the names of its
17  * contributors may be used to endorse or promote products derived
18  * from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  *
32  * Contact: Richard S. Hall (heavy@ungoverned.org)
33  * Contributor(s):
34  *
35 **/

36 package org.ungoverned.oscar;
37
38 import java.io.File JavaDoc;
39 import java.util.Map JavaDoc;
40
41 import org.osgi.framework.BundleActivator;
42
43 /**
44  * <p>
45  * This interface represents an individual cached bundle in the
46  * bundle cache. Oscar uses this interface to access all information
47  * about the associated bundle's cached information. Classes that implement
48  * this interface will be related to a specific implementation of the
49  * <tt>BundleCache</tt> interface.
50  * </p>
51  * @see org.ungoverned.oscar.BundleCache
52 **/

53 public interface BundleArchive
54 {
55     /**
56      * <p>
57      * Returns the identifier of the bundle associated with this archive.
58      * </p>
59      * @return the identifier of the bundle associated with this archive.
60     **/

61     public long getId();
62     
63     /**
64      * <p>
65      * Returns the location string of the bundle associated with this archive.
66      * </p>
67      * @return the location string of the bundle associated with this archive.
68      * @throws java.lang.Exception if any error occurs.
69     **/

70     public String JavaDoc getLocation()
71         throws Exception JavaDoc;
72
73     /**
74      * <p>
75      * Returns the persistent state of the bundle associated with the archive;
76      * this value will be either <tt>Bundle.INSTALLED</tt> or <tt>Bundle.ACTIVE</tt>.
77      * </p>
78      * @return the persistent state of the bundle associated with this archive.
79      * @throws java.lang.Exception if any error occurs.
80     **/

81     public int getPersistentState()
82         throws Exception JavaDoc;
83
84     /**
85      * <p>
86      * Sets the persistent state of the bundle associated with this archive;
87      * this value will be either <tt>Bundle.INSTALLED</tt> or <tt>Bundle.ACTIVE</tt>.
88      * </p>
89      * @param state the new bundle state to write to the archive.
90      * @throws java.lang.Exception if any error occurs.
91     **/

92     public void setPersistentState(int state)
93         throws Exception JavaDoc;
94
95     /**
96      * <p>
97      * Returns the start level of the bundle associated with this archive.
98      * </p>
99      * @return the start level of the bundle associated with this archive.
100      * @throws java.lang.Exception if any error occurs.
101     **/

102     public int getStartLevel()
103         throws Exception JavaDoc;
104
105     /**
106      * <p>
107      * Sets the start level of the bundle associated with this archive.
108      * </p>
109      * @param level the new bundle start level to write to the archive.
110      * @throws java.lang.Exception if any error occurs.
111     **/

112     public void setStartLevel(int level)
113         throws Exception JavaDoc;
114
115     /**
116      * <p>
117      * Returns an appropriate data file for the bundle associated with the
118      * archive using the supplied file name.
119      * </p>
120      * @return a <tt>File</tt> corresponding to the requested data file for
121      * the bundle associated with this archive.
122      * @throws java.lang.Exception if any error occurs.
123     **/

124     public File JavaDoc getDataFile(String JavaDoc fileName)
125         throws Exception JavaDoc;
126
127     /**
128      * <p>
129      * Returns the persistent bundle activator of the bundle associated with
130      * this archive; this is a non-standard OSGi method that is only called
131      * when Oscar is running in non-strict OSGi mode.
132      * </p>
133      * @param loader the class loader to use when trying to instantiate
134      * the bundle activator.
135      * @return the persistent bundle activator of the bundle associated with
136      * this archive.
137      * @throws java.lang.Exception if any error occurs.
138     **/

139     public BundleActivator getActivator(ClassLoader JavaDoc loader)
140         throws Exception JavaDoc;
141
142     /**
143      * <p>
144      * Sets the persistent bundle activator of the bundle associated with
145      * this archive; this is a non-standard OSGi method that is only called
146      * when Oscar is running in non-strict OSGi mode.
147      * </p>
148      * @param obj the new persistent bundle activator to write to the archive.
149      * @throws java.lang.Exception if any error occurs.
150     **/

151     public void setActivator(Object JavaDoc obj)
152         throws Exception JavaDoc;
153
154     /**
155      * <p>
156      * Returns the number of revisions of the bundle associated with the
157      * archive. When a bundle is updated, the previous version of the bundle
158      * is maintained along with the new revision until old revisions are
159      * purged. The revision count reflects how many revisions of the bundle
160      * are currently available in the cache.
161      * </p>
162      * @return the number of revisions of the bundle associated with this archive.
163      * @throws java.lang.Exception if any error occurs.
164     **/

165     public int getRevisionCount()
166         throws Exception JavaDoc;
167
168     /**
169      * <p>
170      * Returns the main attributes of the JAR file manifest header of the
171      * specified revision of the bundle associated with this archive. The
172      * returned map should be case insensitive.
173      * </p>
174      * @param revision the specified revision.
175      * @return the case-insensitive JAR file manifest header of the specified
176      * revision of the bundle associated with this archive.
177      * @throws java.lang.Exception if any error occurs.
178     **/

179     public Map JavaDoc getManifestHeader(int revision)
180         throws Exception JavaDoc;
181
182     /**
183      * <p>
184      * Returns an array of <tt>String</tt>s that represent the class path of
185      * the specified revision of the bundle associated with this archive.
186      * Currently, these values are restricted to absolute paths in the file
187      * system, but this may be lifted in the future (perhaps they should be
188      * <tt>ResourceSource</tt>s from the Module Loader.
189      * </p>
190      * @param revision the specified revision.
191      * @return a <tt>String</tt> array of the absolute path names that
192      * comprise the class path of the specified revision of the
193      * bundle associated with this archive.
194      * @throws java.lang.Exception if any error occurs.
195     **/

196     public String JavaDoc[] getClassPath(int revision)
197         throws Exception JavaDoc;
198
199     /**
200      * <p>
201      * Returns the absolute file path for the specified native library of the
202      * specified revision of the bundle associated with this archive.
203      * </p>
204      * @param revision the specified revision.
205      * @param libName the name of the library.
206      * @return a <tt>String</tt> that contains the absolute path name to
207      * the requested native library of the specified revision of the
208      * bundle associated with this archive.
209      * @throws java.lang.Exception if any error occurs.
210     **/

211     public String JavaDoc findLibrary(int revision, String JavaDoc libName)
212         throws Exception JavaDoc;
213 }
Popular Tags