001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.pde.core;
011:
012: import java.io.InputStream;
013:
014: import org.eclipse.core.resources.IResource;
015: import org.eclipse.core.runtime.CoreException;
016:
017: /**
018: * A generic model. Classes that implement this interface are expected to be
019: * able to:
020: * <ul>
021: * <li>Load from an input stream
022: * <li>Reload (reset, load, fire 'world change')
023: * <li>Dispose (clear all the data and reset)
024: * <li>Be associated with a resource (optional)
025: * </ul>
026: * If a model is not created from a workspace resource file, its underlying
027: * resource will be <samp>null </samp>.
028: *
029: * @since 2.0
030: */
031: public interface IModel extends IBaseModel {
032: /**
033: * Returns a string found in the resource bundle associated with this model
034: * for the provided key.
035: *
036: * @param key
037: * the name to use for bundle lookup
038: * @return the string for the key in the resource bundle, or the key itself
039: * if not found
040: */
041: String getResourceString(String key);
042:
043: /**
044: * Returns a workspace resource that this model is created from. Load/reload
045: * operations are not directly connected with the resource (although they
046: * can be). In some cases, models will load from a buffer (an editor
047: * document) rather than a resource. However, the buffer will eventually be
048: * synced up with this resource.
049: * <p>
050: * With the caveat of stepped loading, all other properties of the
051: * underlying resource could be used directly (path, project etc.).
052: *
053: * @return a workspace resource (file) that this model is associated with,
054: * or <samp>null </samp> if the model is not created from a
055: * resource.
056: */
057: public IResource getUnderlyingResource();
058:
059: /**
060: * Tests if this model is loaded and can be used.
061: *
062: * @return <code>true</code> if the model has been loaded
063: */
064: boolean isLoaded();
065:
066: /**
067: * Tests if this model is in sync with the storage object it was loaded
068: * from. Models loaded from resources are in sync if underlying resources
069: * are in sync. Models loaded from files on the file systems are in sync if
070: * the time stamp matches the model time stamp.
071: *
072: * @return <code>true</code> if the model is in sync with the file system.
073: */
074: boolean isInSync();
075:
076: /**
077: * Returns the last modification time stamp. The model itself does not have
078: * the time stamp. It is 'borrowed' from the underlying physical object.
079: *
080: * @return the time stamp of the underlying physical object.
081: */
082: long getTimeStamp();
083:
084: /**
085: * Loads the model directly from an underlying resource. This method does
086: * nothing if this model has no underlying resource or if there is a buffer
087: * stage between the model and the resource.
088: *
089: * @throws CoreException
090: * if errors are encountered during the loading.
091: */
092: public void load() throws CoreException;
093:
094: /**
095: * Loads the model from the provided input stream. This method throws a
096: * CoreException if errors are encountered during the loading. Upon
097: * succesful load, 'isLoaded()' should return <samp>true </samp>.
098: *
099: * @param source
100: * an input stream that should be parsed to load the model
101: * @param outOfSync
102: * if true, time stamp will not be updated to maintain
103: * out-of-sync state of the model.
104: * @throws CoreException
105: * if errors are encountered during the loading.
106: */
107: public void load(InputStream source, boolean outOfSync)
108: throws CoreException;
109:
110: /**
111: * Reload is a version of 'load' operation that has the following steps:
112: * <ul>
113: * <li>Reset the model
114: * <li>Load the model
115: * <li>Fire "world changed" event
116: * </ul>
117: * Reload operation is used when a model that is already in use is
118: * invalidated by a change in the underlying buffer or resource. Since we
119: * don't know the extent of the change, the only safe thing to do is to
120: * reparse the buffer to sync up. The event that is subsequently fired
121: * should be used by listeners to discard all caches and/or fully refresh
122: * views that shows any portion of the model.
123: *
124: * @param source
125: * an input stream that should be parsed to load the model.
126: * @param outOfSync
127: * if true, the timestamp will not be updated to maintain
128: * out-of-sync state of the model.
129: * @throws CoreException
130: * if errors are encountered during the reloading.
131: */
132: public void reload(InputStream source, boolean outOfSync)
133: throws CoreException;
134:
135: /**
136: * Returns whether this model needs to react to changes in source and
137: * reconcile them. Only model instances used in editors need to perform this
138: * task.
139: *
140: * @return <code>true</code> if this is a reconciling model,
141: * <code>false</code> otherwise.
142: */
143: public boolean isReconcilingModel();
144: }
|