IModel


1   /*******************************************************************************
2    * Copyright (c) 2000, 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.pde.core;
12  import java.io.InputStream  ;
13  
14  import org.eclipse.core.resources.IResource;
15  import org.eclipse.core.runtime.CoreException;
16  /**
17   * A generic model. Classes that implement this interface are expected to be
18   * able to:
19   * <ul>
20   * <li>Load from an input stream
21   * <li>Reload (reset, load, fire 'world change')
22   * <li>Dispose (clear all the data and reset)
23   * <li>Be associated with a resource (optional)
24   * </ul>
25   * If a model is not created from a workspace resource file, its underlying
26   * resource will be <samp>null </samp>.
27   * 
28   * @since 2.0
29   */
30  public interface IModel extends IBaseModel {
31      /**
32       * Returns a string found in the resource bundle associated with this model
33       * for the provided key.
34       * 
35       * @param key
36       *            the name to use for bundle lookup
37       * @return the string for the key in the resource bundle, or the key itself
38       *         if not found
39       */
40      String   getResourceString(String   key);
41      /**
42       * Returns a workspace resource that this model is created from. Load/reload
43       * operations are not directly connected with the resource (although they
44       * can be). In some cases, models will load from a buffer (an editor
45       * document) rather than a resource. However, the buffer will eventually be
46       * synced up with this resource.
47       * <p>
48       * With the caveat of stepped loading, all other properties of the
49       * underlying resource could be used directly (path, project etc.).
50       * 
51       * @return a workspace resource (file) that this model is associated with,
52       *         or <samp>null </samp> if the model is not created from a
53       *         resource.
54       */
55      public IResource getUnderlyingResource();
56      /**
57       * Tests if this model is loaded and can be used.
58       * 
59       * @return <code>true</code> if the model has been loaded
60       */
61      boolean isLoaded();
62      /**
63       * Tests if this model is in sync with the storage object it was loaded
64       * from. Models loaded from resources are in sync if underlying resources
65       * are in sync. Models loaded from files on the file systems are in sync if
66       * the time stamp matches the model time stamp.
67       * 
68       * @return <code>true</code> if the model is in sync with the file system.
69       */
70      boolean isInSync();
71      /**
72       * Returns the last modification time stamp. The model itself does not have
73       * the time stamp. It is 'borrowed' from the underlying physical object.
74       * 
75       * @return the time stamp of the underlying physical object.
76       */
77      long getTimeStamp();
78      /**
79       * Loads the model directly from an underlying resource. This method does
80       * nothing if this model has no underlying resource or if there is a buffer
81       * stage between the model and the resource.
82       * 
83       * @throws CoreException
84       *             if errors are encountered during the loading.
85       */
86      public void load() throws CoreException;
87      /**
88       * Loads the model from the provided input stream. This method throws a
89       * CoreException if errors are encountered during the loading. Upon
90       * succesful load, 'isLoaded()' should return <samp>true </samp>.
91       * 
92       * @param source
93       *            an input stream that should be parsed to load the model
94       * @param outOfSync
95       *            if true, time stamp will not be updated to maintain
96       *            out-of-sync state of the model.
97       * @throws CoreException
98       *             if errors are encountered during the loading.
99       */
100     public void load(InputStream   source, boolean outOfSync)
101             throws CoreException;
102     /**
103      * Reload is a version of 'load' operation that has the following steps:
104      * <ul>
105      * <li>Reset the model
106      * <li>Load the model
107      * <li>Fire "world changed" event
108      * </ul>
109      * Reload operation is used when a model that is already in use is
110      * invalidated by a change in the underlying buffer or resource. Since we
111      * don't know the extent of the change, the only safe thing to do is to
112      * reparse the buffer to sync up. The event that is subsequently fired
113      * should be used by listeners to discard all caches and/or fully refresh
114      * views that shows any portion of the model.
115      * 
116      * @param source
117      *            an input stream that should be parsed to load the model.
118      * @param outOfSync
119      *            if true, the timestamp will not be updated to maintain
120      *            out-of-sync state of the model.
121      * @throws CoreException
122      *             if errors are encountered during the reloading.
123      */
124     public void reload(InputStream   source, boolean outOfSync)
125             throws CoreException;
126     /**
127      * Returns whether this model needs to react to changes in source and
128      * reconcile them. Only model instances used in editors need to perform this
129      * task.
130      * 
131      * @return <code>true</code> if this is a reconciling model,
132      *         <code>false</code> otherwise.
133      */
134     public boolean isReconcilingModel();
135 }
136
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags