BundleCache


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.InputStream  ;
39  
40  /**
41   * <p>
42   * This interface represents the storage mechanism that Oscar uses for
43   * caching bundles. It is possible for multiple implementations of
44   * this interface to exist for different storage technologies, such as the
45   * file system, memory, or a database. Oscar includes a default implementation
46   * of this interface that uses the file system. Oscar allows you to specify
47   * alternative implementations to use by specifying a class name via the
48   * <tt>oscar.cache.class</tt> system property. Bundle cache implemenations
49   * should implement this interface and provide a default constructor.
50   * </p>
51   * @see org.ungoverned.oscar.BundleArchive
52  **/
53  public interface BundleCache
54  {
55      /**
56       * <p>
57       * This method is called before using the BundleCache implementation
58       * to initialize it and to pass it a reference to its associated
59       * Oscar instance. The main purpose for passing the <tt>BundleCache</tt>
60       * implementation a reference to its Oscar instance is to allow it
61       * to use <tt>Oscar.getConfigProperty()</tt> to access system property values;
62       * the <tt>BundleCache</tt> implementation should not use
63       * <tt>System.getProperty()</tt> directly. <tt>Oscar.getConfigProperty()</tt>
64       * provides access to properties passed into the Oscar instance's
65       * constructor. If no properties were passed in to the constructor
66       * then it searches <tt>System.getProperty()</tt>. This approach allows
67       * multiple instances of Oscar to exist in memory at the same time, but for
68       * them to be configured differently. For example, an application may
69       * want two instances of Oscar, where each instance stores their cache
70       * in a different location in the file system. When using multiple
71       * instances of Oscar in memory at the same time, system properties
72       * should be avoided and all properties should be passed in to Oscar's
73       * constructor.
74       * </p>
75       * @param oscar the Oscar instance associated with the bundle cache.
76       * @throws Exception if any error occurs.
77      **/
78      public void initialize(Oscar oscar)
79          throws Exception  ;
80  
81      /**
82       * <p>
83       * Returns all cached bundle archives.
84       * </p>
85       * @return an array of all cached bundle archives.
86       * @throws Exception if any error occurs.
87      **/
88      public BundleArchive[] getArchives()
89          throws Exception  ;
90  
91      /**
92       * <p>
93       * Returns the bundle archive associated with the specified
94       * bundle indentifier.
95       * </p>
96       * @param id the identifier of the bundle archive to retrieve.
97       * @return the bundle archive assocaited with the specified bundle identifier.
98       * @throws Exception if any error occurs.
99      **/
100     public BundleArchive getArchive(long id)
101         throws Exception  ;
102 
103     /**
104      * <p>
105      * Creates a new bundle archive for the specified bundle
106      * identifier using the supplied location string and input stream. The
107      * contents of the bundle JAR file should be read from the supplied
108      * input stream, which will not be <tt>null</tt>. The input stream is
109      * closed by the caller; the implementation is only responsible for
110      * closing streams it opens. If this method completes successfully, then
111      * it means that the initial bundle revision of the specified bundle was
112      * successfully cached.
113      * </p>
114      * @param id the identifier of the bundle associated with the new archive.
115      * @param location the location of the bundle associated with the new archive.
116      * @param is the input stream to the bundle's JAR file.
117      * @return the created bundle archive.
118      * @throws Exception if any error occurs.
119     **/
120     public BundleArchive create(long id, String   location, InputStream   is)
121         throws Exception  ;
122 
123     /**
124      * <p>
125      * Saves an updated revision of the specified bundle to
126      * the bundle cache using the supplied input stream. The contents of the
127      * updated bundle JAR file should be read from the supplied input stream,
128      * which will not be <tt>null</tt>. The input stream is closed by the
129      * caller; the implementation is only responsible for closing streams
130      * it opens. Updating a bundle in the cache does not replace the current
131      * revision of the bundle, it makes a new revision available. If this
132      * method completes successfully, then it means that the number of
133      * revisions of the specified bundle has increased by one.
134      * </p>
135      * @param ba the bundle archive of the bundle to update.
136      * @param is the input stream to the bundle's updated JAR file.
137      * @throws Exception if any error occurs.
138     **/
139     public void update(BundleArchive ba, InputStream   is)
140         throws Exception  ;
141 
142     /**
143      * <p>
144      * Purges all old revisions of the specified bundle from
145      * the cache. If this method completes successfully, then it means that
146      * only the most current revision of the bundle should exist in the cache.
147      * </p>
148      * @param ba the bundle archive of the bundle to purge.
149      * @throws Exception if any error occurs.
150     **/
151     public void purge(BundleArchive ba)
152         throws Exception  ;
153 
154     /**
155      * <p>
156      * Removes the specified bundle from the cache. If this method
157      * completes successfully, there should be no trace of the removed bundle
158      * in the cache.
159      * </p>
160      * @param ba the bundle archive of the bundle to remove.
161      * @throws Exception if any error occurs.
162     **/
163     public void remove(BundleArchive ba)
164         throws Exception  ;
165 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags