PersistenceService


1   /*
2    * @(#)PersistenceService.java  1.22 04/03/12
3    * 
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.jnlp;
9   
10  import java.io.InputStream;
11  import java.io.OutputStream;
12  import java.io.RandomAccessFile;
13  import java.io.IOException;
14  import java.io.FileNotFoundException;
15  import java.net.URL;
16  import java.net.MalformedURLException;
17  
18  /**
19   * <code>PersistenceService</code> provides methods for storing data
20   * locally on the client system, even for applications that are running
21   * in the untrusted execution environment.  The service is somewhat
22   * similar to that which the cookie mechanism provides to HTML-based
23   * applications.
24   * <p>
25   * Each entry in the persistence data store is named with a URL.
26   * This provides a similar hierarchical structure as a traditional file
27   * system.
28   * <p>
29   * An application is only allowed to access data stored with a URL that
30   * is based on its codebase.  For example, given the codebase
31   * <code>http://www.mysite.com/apps/App1/</code>, the application
32   * would be allowed to access the data at the associated URLs:
33   * <ul>
34   *    <li><code>http://www.mysite.com/apps/App1/</code>
35   *    <li><code>http://www.mysite.com/apps/</code>
36   *    <li><code>http://www.mysite.com/</code>
37   * </ul>
38   * <p>
39   * This scheme allows sharing of data between different applications from
40   * the same host.  For example, if another application is located at
41   * <code>http://www.mysite.com/apps/App2/</code>, then they can share data
42   * between them in the <code>http://www.mysite.com/</code> and
43   * <code>http://www.mysite.com/apps/</code> directories.
44   * <p>
45   * A JNLP client should track the amount of storage that a given
46   * application uses.  A <code>PersistenceService</code> implementation
47   * provides methods to get the current storage usage and limits and to
48   * request more storage. Storage is allocated on a per file basis, but a
49   * JNLP Client will typically grant or deny the request based on the total
50   * storage is use by an application.
51   * <p>
52   * Data stored using this mechanism is intended to be a local copy of
53   * data stored on a remote server.  The individual entries can be
54   * tagged as either <i>cached</i>, meaning the server has an up-to-date
55   * copy, <i>dirty</i>, meaning the server does not have an up-to-date
56   * copy, or <i>temporary</i>, meaning that the file can always be
57   * recreated.
58   *
59   * @since 1.0
60   */
61  
62  public interface PersistenceService {
63      
64      public static final int CACHED = 0;
65      public static final int TEMPORARY = 1;
66      public static final int DIRTY = 2;
67      
68      /**
69       * Creates a new persistent storage entry on the client side named with
70       * the given URL.
71       *
72       * @param url       the URL representing the name of the entry in the
73       *                  persistent data store.
74       *
75       * @param maxsize   maximum size of storage that can be written to this
76       *                  entry.
77       *
78       * @return          the maximum size of storage that got granted, in bytes.
79       *
80       * @throws MalformedURLException if the application is denied access to
81       *                               the persistent data store represented by
82       *                               the given URL.
83       * @throws IOException if an I/O exception occurs, or the entry already exists.
84       */
85      public long create(URL url, long maxsize)
86          throws MalformedURLException, IOException;
87  
88      /**
89       * Returns a <code>FileContents</code> object representing the contents
90       * of this file.
91       *
92       * @param url     the URL representing the persistent data store entry.
93       *
94       * @return the file contents as a FileContents.
95       *
96       * @throws IOException if an I/O error occurs.
97       * @throws MalformedURLException if the application is denied access to
98       *                               the persistent data store represented by
99       *                               the given URL.
100      * @throws FileNotFoundException if a persistence store for the given URL
101      *                               is not found.
102      */
103     public FileContents get(URL url)
104         throws MalformedURLException, IOException, FileNotFoundException;
105         
106     /**
107      * Removes the stream associated with the given URL from the
108      * client-side date persistence store.
109      *
110      * @param url     the URL representing the entry to delete from
111      *                the persistent data store.
112      *
113      * @throws MalformedURLException if the application is denied access to
114      *                               the persistent data store represented by
115      *                               the given URL.
116      * @throws IOException if an I/O exception occurs.
117      */
118     public void delete(URL url)
119         throws MalformedURLException, IOException;
120     
121     /**
122      * Returns an array of Strings containing the names of all the
123      * entries for a given URL.
124      *
125      * @param url    the URL representing the root directory to search for
126      *               entry names.
127      *
128      * @return       a <code>String</code> array containing the entries
129      *               names.
130      * @throws MalformedURLException if the application is denied access to
131      *                               the persistent data store represented by
132      *                               the given URL.
133      * @throws IOException if an I/O exception occurs.
134      */
135     public String[] getNames(URL url) throws MalformedURLException, IOException;
136     
137     /**
138      * Returns an <code>int</code> corresponding to the current value
139      * of the tag for the persistent data store entry associated with the
140      * given URL.
141      *
142      * @param url     the URL representing the persistent data store entry
143      *                for which the tag value is requested.
144      *
145      * @return        an <code>int</code> containing one of the following
146      *                tag values:
147      *                <ul>
148      *                    <li> {@link PersistenceService#CACHED}
149      *                    <li> {@link PersistenceService#TEMPORARY}
150      *                    <li> {@link PersistenceService#DIRTY}
151      *                </ul>
152      *
153      * @throws MalformedURLException if the application is denied access to
154      *                               the persistent data store represented by
155      *                               the given URL.
156      * @throws IOException if an I/O exception occurs.
157      */
158     public int getTag(URL url)
159         throws MalformedURLException, IOException;
160     
161     /**
162      * Tags the persistent data store entry associated with the given URL
163      * with the given tag value.
164      *
165      * @param url     the URL representing the persistent data store entry
166      *                for which to set the tag value.
167      *
168      * @param tag     the tag value to set.
169      *
170      * @throws MalformedURLException if the application is denied access to
171      *                               the persistent data store represented by
172      *                               the given URL.
173      * @throws IOException if an I/O exception occurs.
174      */
175     public void setTag(URL url, int tag)
176         throws MalformedURLException, IOException;
177     
178 }
179 
180
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Java Books Remove Frame
Popular Tags