/*******************************************************************************
* Copyright (c) 2000, 2009 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.core.resources;
/**
* A workspace description represents the workspace preferences. It can be
* used to query the current preferences and set new ones. The workspace
* preference values are stored in the preference store and are also accessible
* via the preference mechanism. Constants for the preference keys are found
* on the <code>ResourcesPlugin</code> class.
*
* @see IWorkspace#getDescription()
* @see IWorkspace#setDescription(IWorkspaceDescription)
* @see IWorkspace#newProjectDescription(String)
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*/
public interface IWorkspaceDescription {
/**
* Returns the order in which projects in the workspace should be built.
* The returned value is <code>null</code> if the workspace's default build
* order is being used.
*
* @return the names of projects in the order they will be built,
* or <code>null</code> if the default build order should be used
* @see #setBuildOrder(String[])
* @see ResourcesPlugin#PREF_BUILD_ORDER
*/
public String[] getBuildOrder();
/**
* Returns the maximum length of time, in milliseconds, a file state should be
* kept in the local history. This setting is ignored by the workspace when
* <code>isApplyFileStatePolicy()</code> returns <code>false</code>.
*
* @return the maximum time a file state should be kept in the local history
* represented in milliseconds
* @see #setFileStateLongevity(long)
* @see #isApplyFileStatePolicy()
* @see ResourcesPlugin#PREF_FILE_STATE_LONGEVITY
*/
public long getFileStateLongevity();
/**
* Returns the maximum number of times that the workspace should rebuild when
* builders affect projects that have already been built.
*
* @return the maximum number of times that the workspace should rebuild when
* builders affect projects that have already been built.
* @see #setMaxBuildIterations(int)
* @see ResourcesPlugin#PREF_MAX_BUILD_ITERATIONS
* @since 2.1
*/
public int getMaxBuildIterations();
/**
* Returns the maximum number of states per file that can be stored in the local history.
* This setting is ignored by the workspace when <code>isApplyFileStatePolicy()</code>
* returns <code>false</code>.
*
* @return the maximum number of states per file that can be stored in the local history
* @see #setMaxFileStates(int)
* @see #isApplyFileStatePolicy()
* @see ResourcesPlugin#PREF_MAX_FILE_STATES
*/
public int getMaxFileStates();
/**
* Returns the maximum permitted size of a file, in bytes, to be stored in the
* local history. This setting is ignored by the workspace when
* <code>isApplyFileStatePolicy()</code> returns <code>false</code>.
*
* @return the maximum permitted size of a file to be stored in the local history
* @see #setMaxFileStateSize(long)
* @see #isApplyFileStatePolicy()
* @see ResourcesPlugin#PREF_MAX_FILE_STATE_SIZE
*/
public long getMaxFileStateSize();
/**
* Returns whether file states are discarded according to the policy specified by
* <code>setFileStateLongevity(long)</code>, <code>setMaxFileStates(int)</code>
* and <code>setMaxFileStateSize(long)</code> methods.
*
* @return <code>true</code> if file states are removed due to the policy,
* <code>false</code> otherwise
* @see #setApplyFileStatePolicy(boolean)
* @see #setFileStateLongevity(long)
* @see #setMaxFileStates(int)
* @see #setMaxFileStateSize(long)
* @see ResourcesPlugin#PREF_APPLY_FILE_STATE_POLICY
* @since 3.6
*/
public boolean isApplyFileStatePolicy();
/**
* Returns the interval between automatic workspace snapshots.
*
* @return the amount of time in milliseconds between automatic workspace snapshots
* @see #setSnapshotInterval(long)
* @see ResourcesPlugin#PREF_SNAPSHOT_INTERVAL
* @since 2.0
*/
public long getSnapshotInterval();
/**
* Returns whether this workspace performs autobuilds.
*
* @return <code>true</code> if autobuilding is on, otherwise
* <code>false</code>
* @see #setAutoBuilding(boolean)
* @see ResourcesPlugin#PREF_AUTO_BUILDING
*/
public boolean isAutoBuilding();
/**
* Records whether this workspace performs autobuilds.
* <p>
* When autobuild is on, any changes made to a project and its
* resources automatically triggers an incremental build of the workspace.
* </p>
* <p>
* Users must call <code>IWorkspace.setDescription</code> before changes
* made to this description take effect.
* </p>
*
* @param value <code>true</code> to turn on autobuilding,
* and <code>false</code> to turn it off
* @see IWorkspace#setDescription(IWorkspaceDescription)
* @see #isAutoBuilding()
* @see ResourcesPlugin#PREF_AUTO_BUILDING
*/
public void setAutoBuilding(boolean value);
/**
* Sets the order in which projects in the workspace should be built.
* Projects not named in this list are built in a default order defined
* by the workspace. Set this value to <code>null</code> to use the
* default ordering for all projects. Projects not named in the list are
* built in unspecified order after all ordered projects.
* <p>
* Users must call <code>IWorkspace.setDescription</code> before changes
* made to this description take effect.
* </p>
*
* @param value the names of projects in the order in which they are built,
* or <code>null</code> to use the workspace's default order for all projects
* @see IWorkspace#setDescription(IWorkspaceDescription)
* @see #getBuildOrder()
* @see ResourcesPlugin#PREF_BUILD_ORDER
*/
public void setBuildOrder(String[] value);
/**
* Sets the maximum time, in milliseconds, a file state should be kept in the
* local history. This setting is ignored by the workspace when <code>setApplyFileStatePolicy(boolean)
* </code> is set to false.
* <p>
* Users must call <code>IWorkspace.setDescription</code> before changes
* made to this description take effect.
* </p>
*
* @param time the maximum number of milliseconds a file state should be
* kept in the local history
* @see IWorkspace#setDescription(IWorkspaceDescription)
* @see #getFileStateLongevity()
* @see #setApplyFileStatePolicy(boolean)
* @see ResourcesPlugin#PREF_FILE_STATE_LONGEVITY
*/
public void setFileStateLongevity(long time);
/**
* Sets the maximum number of times that the workspace should rebuild when
* builders affect projects that have already been built.
* <p>
* Users must call <code>IWorkspace.setDescription</code> before changes
* made to this description take effect.
* </p>
*
* @param number the maximum number of times that the workspace should rebuild
* when builders affect projects that have already been built.
* @see IWorkspace#setDescription(IWorkspaceDescription)
* @see #getMaxBuildIterations()
* @see ResourcesPlugin#PREF_MAX_BUILD_ITERATIONS
* @since 2.1
*/
public void setMaxBuildIterations(int number);
/**
* Sets the maximum number of states per file that can be stored in the local history.
* If the maximum number is reached, older states are removed in favor of
* new ones. This setting is ignored by the workspace when <code>setApplyFileStatePolicy(boolean)
* </code> is set to <code>false</code>.
* <p>
* Users must call <code>IWorkspace.setDescription</code> before changes
* made to this description take effect.
* </p>
*
* @param number the maximum number of states per file that can be stored in the local history
* @see IWorkspace#setDescription(IWorkspaceDescription)
* @see #getMaxFileStates()
* @see #setApplyFileStatePolicy(boolean)
* @see ResourcesPlugin#PREF_MAX_FILE_STATES
*/
public void setMaxFileStates(int number);
/**
* Sets the maximum permitted size of a file, in bytes, to be stored in the
* local history. This setting is ignored by the workspace when <code>setApplyFileStatePolicy(boolean)
* </code> is set to <code>false</code>.
* <p>
* Users must call <code>IWorkspace.setDescription</code> before changes
* made to this description take effect.
* </p>
*
* @param size the maximum permitted size of a file to be stored in the local history
* @see IWorkspace#setDescription(IWorkspaceDescription)
* @see #getMaxFileStateSize()
* @see #setApplyFileStatePolicy(boolean)
* @see ResourcesPlugin#PREF_MAX_FILE_STATE_SIZE
*/
public void setMaxFileStateSize(long size);
/**
* Sets whether file states are discarded according to the policy specified by
* <code>setFileStateLongevity(long)</code>, <code>setMaxFileStates(int)</code>
* and <code>setMaxFileStateSize(long)</code> methods.
* <p>
* Users must call <code>IWorkspace.setDescription</code> before changes
* made to this description take effect.
* </p>
*
* @param apply <code>true</code> if file states are removed due to the policy,
* <code>false</code> otherwise
* @see IWorkspace#setDescription(IWorkspaceDescription)
* @see #setFileStateLongevity(long)
* @see #setMaxFileStates(int)
* @see #setMaxFileStateSize(long)
* @see #isApplyFileStatePolicy()
* @see ResourcesPlugin#PREF_APPLY_FILE_STATE_POLICY
* @since 3.6
*/
public void setApplyFileStatePolicy(boolean apply);
/**
* Sets the interval between automatic workspace snapshots. The new interval
* will only take effect after the next snapshot.
* <p>
* Users must call <code>IWorkspace.setDescription</code> before changes
* made to this description take effect.
* </p>
*
* @param delay the amount of time in milliseconds between automatic workspace snapshots
* @see IWorkspace#setDescription(IWorkspaceDescription)
* @see #getSnapshotInterval()
* @see ResourcesPlugin#PREF_SNAPSHOT_INTERVAL
* @since 2.0
*/
public void setSnapshotInterval(long delay);
}