com.starteam
Class CheckoutManager

java.lang.Object
  com.starteam.CheckoutManager

All Implemented Interfaces:

StreamUtils.Listener

public class CheckoutManager
extends java.lang.Object
implements StreamUtils.Listener

Provides a way to check out multiple files, applying a consistent set of options across all files. Files may be aggregated or overwritten (using the different flavors of the checkout api's) until ready to commit all the changes The commit() method must be called to save all identified changes to the local file system Files will be checked out either from the StarTeam server or from the closest cache agent If a cache agent is being used, file checkouts are multi-threaded, and are based on the HTTP protocol The commit is non-transactional, and is executed in two primary phases During the first phase of the checkout, events are fired to the calling client application, at which point, the application may decide to overwrite earlier decisions, such as ignoring certain files, force checking out others, checking out to a different stream, etc. Usage CheckoutManager cm = myView.createCheckoutManager(); cm.checkout(file1); cm.checkoutTo(file2, new java.io.File("c://myprojects//myworkspace//file2.txt"); cm.checkout(file3, new CheckoutOptions(myView)); if (cm.canCommit()) cm.commit();

Nested Class Summary

static class	CheckoutManager.Progress Information on the progress of a checkout operation from CheckoutManager.
static class	CheckoutManager.WebCacheCheckoutManager

Method Summary

void	addCheckoutListener(CheckoutListener listener) Adds a listener for checkout-related events.
boolean	bytesTransferred(int bytes) the number of bytes transferred from the server to the client
boolean	canCommit() returns true if the session can be committed For the session to be in a commit-able state, all files being checked out should be in a relevant state, e.g.
void	checkout(File starTeamFile) Checks out a single file to the default location.
void	checkout(File[] files) Checks out the given set of files.
void	checkout(File starTeamFile, CheckoutOptions options) Checks out a file with the specified set of options.
void	checkout(Folder folder) Checks out all the files in the given folder.
void	checkout(Folder folder, int depth) Checks out all the files in the given folder, and in all sub-folders to the given depth.
void	checkoutTo(File starTeamFile, java.io.File diskFile) Checks out a file in the context of the specified starTeam File Object to the specified file system disk file.
void	checkoutTo(File starTeamFile, java.io.OutputStream stream) Checks out a single file to an output stream.
java.lang.Object	clone() clone a checkout manager from this one
File[]	commit() Commit all the changes to the local file system.
CheckoutOptions	getOptions() Gets the checkout options currently in effect.
CheckoutManager.Progress	getProgress() Gets a snapshot of the state of the current checkout operation.
View	getView() returns the containing view
boolean	hasCheckoutListeners() Returns true if there is at least one registered listener for checkout events
void	ignore(Item starTeamItem) Remove this item from consideration for the commit If the item was to be checked out, it will not be checked out If the item is a folder, then all child files, descendant folders and child files of descendant folders will be removed from consideration
boolean	isCanceled() Indicates whether or not pending checkout operations have been canceled.
boolean	isRunning() Determines whether or not there is currently a checkout operation in progress.
void	removeCheckoutListener(CheckoutListener listener) Removes a listener for checkout-related events.
void	setCanceled() Cancels any pending checkout operations.
void	setOptions(CheckoutOptions checkoutOptions) Changes the checkout options currently in effect.
long	size() returns a count of the amount of work to be done by this manager
java.lang.String	toString() Gets a string representation of this CheckoutManager, useful for debugging.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

clone

public java.lang.Object clone()

clone a checkout manager from this one

Overrides:

clone in class java.lang.Object

Returns:

Object a new checkout manager

setCanceled

public void setCanceled()

Cancels any pending checkout operations.

See Also:

CheckoutManager.isCanceled()

isCanceled

public boolean isCanceled()

Indicates whether or not pending checkout operations have been canceled.

Returns:

true if pending checkout operations have been canceled, and false otherwise.

See Also:

CheckoutManager.setCanceled()

checkoutTo

public void checkoutTo(File starTeamFile,
                       java.io.File diskFile)
                throws java.io.IOException

Checks out a file in the context of the specified starTeam File Object to the specified file system disk file. Note that the force checkout flag must be set to true for the actual bytes to get checked out and written to the disk file. If not set, an empty file is created on disk. This is by design to satisfy a backward compatibility constraint. Creates a copy of the global options. Subsequent changes to global options do not affect this file

Parameters:

starTeamFile - File a starTeam File Object instance

diskFile - File a java.io.File to checkout to

Throws:

java.io.IOException

See Also:

CheckoutOptions.setForceCheckout(boolean)

checkout

public void checkout(File starTeamFile)

Checks out a single file to the default location. The file is checked out on commit. Creates a copy of the global options. Subsequent changes to global options do not affect this file

Parameters:

starTeamFile - The file to be checked out.

See Also:

CheckoutManager.commit()

checkout

public void checkout(File starTeamFile,
                     CheckoutOptions options)

Checks out a file with the specified set of options. The file is checked out on commit

Parameters:

starTeamFile - The file to checkout

options - the checkout options to use. These options override the default options assigned when this checkout manager was created.

See Also:

CheckoutManager.commit()

checkoutTo

public void checkoutTo(File starTeamFile,
                       java.io.OutputStream stream)

Checks out a single file to an output stream. No status update is performed in this case. Creates a copy of the global options. Subsequent changes to global options do not affect this file

Parameters:

starTeamFile - The file to be checked out.

stream - The stream to which the checked out content is written.

canCommit

public boolean canCommit()

returns true if the session can be committed For the session to be in a commit-able state, all files being checked out should be in a relevant state, e.g. OUT OF DATE or MISSING, or else the ForceCheckout option should be specified

Returns:

true if the session can be committed

size

public long size()

returns a count of the amount of work to be done by this manager

Returns:

a count of the amount of work to be done by this manager

commit

public File[] commit()

Commit all the changes to the local file system. The files will be checked out from the server or the closest cache agent, if one is specified Checkout from CacheAgent is multi-threaded, and uses the HTTP protocol

Returns:

the actual revisions whose contents were checked out

ignore

public void ignore(Item starTeamItem)

Remove this item from consideration for the commit If the item was to be checked out, it will not be checked out If the item is a folder, then all child files, descendant folders and child files of descendant folders will be removed from consideration

Parameters:

starTeamItem -

checkout

public void checkout(File[] files)

Checks out the given set of files. The files are checked out on commit Creates a copy of the global options. Subsequent changes to global options do not affect these files.

Parameters:

files - The files to be checked out.

See Also:

CheckoutManager.commit(), Folder.getItems(com.starteam.Item.Type)

checkout

public void checkout(Folder folder)

Checks out all the files in the given folder. Creates a copy of the global options. Subsequent changes to global options do not affect this folder and its files

Parameters:

folder - The StarTeam folder whose files are to be checked out.

See Also:

Folder, CheckoutManager.checkout(Folder,int)

checkout

public void checkout(Folder folder,
                     int depth)

Checks out all the files in the given folder, and in all sub-folders to the given depth. Creates a copy of the global options. Subsequent changes to global options do not affect these folders and their files

Parameters:

folder - The StarTeam folder whose files are to be checked out.

depth - Indicates which sub-folders also contain files to be checked out. Zero indicates that no sub-folders should be included; 1 indicates that this folder and its immediate child folders should be included; -1 indicates that this folder and all child folders at any depth should be included. -2 indicates that only the folder should be 'checked out'

isRunning

public boolean isRunning()

Determines whether or not there is currently a checkout operation in progress.

Returns:

true if there is currently a checkout operation in progress, and false otherwise.

addCheckoutListener

public void addCheckoutListener(CheckoutListener listener)

Adds a listener for checkout-related events.

Parameters:

listener - Application-specific event handler for checkout-related events.

See Also:

CheckoutListener, CheckoutEvent, CheckoutManager.removeCheckoutListener(com.starteam.events.CheckoutListener)

removeCheckoutListener

public void removeCheckoutListener(CheckoutListener listener)

Removes a listener for checkout-related events.

Parameters:

listener - A previously-registered event handler for checkout-related events.

See Also:

CheckoutManager.addCheckoutListener(com.starteam.events.CheckoutListener)

hasCheckoutListeners

public boolean hasCheckoutListeners()

Returns true if there is at least one registered listener for checkout events

Returns:

boolean true if there is at least one registered listener for checkout events

toString

public java.lang.String toString()

Gets a string representation of this CheckoutManager, useful for debugging.

Overrides:

toString in class java.lang.Object

Returns:

A string representation of this CheckoutManager.

getOptions

public CheckoutOptions getOptions()

Gets the checkout options currently in effect. Note that CheckoutManager wide options should be specified before calling any of the checkout api's.

Note that individual options can be overridden on a file-by-file basis by registering a CheckoutListener, and changing options as necessary in the onStartFile event handler.

Returns:

The checkout options currently in effect.

See Also:

CheckoutOptions, CheckoutManager.addCheckoutListener(com.starteam.events.CheckoutListener)

setOptions

public void setOptions(CheckoutOptions checkoutOptions)

Changes the checkout options currently in effect. Note that CheckoutManager wide options should be specified before calling any of the checkout api's.

Parameters:

checkoutOptions - The new checkout options.

getProgress

public CheckoutManager.Progress getProgress()

Gets a snapshot of the state of the current checkout operation.

Returns:

A snapshot of the state of the current checkout operation.

See Also:

CheckoutManager.Progress, CheckoutManager.isRunning()

getView

public View getView()

returns the containing view

Returns:

View

bytesTransferred

public boolean bytesTransferred(int bytes)

the number of bytes transferred from the server to the client

Specified by:

bytesTransferred in interface StreamUtils.Listener

Parameters:

bytes - the number of bytes transferred from the server to the client

Returns:

boolean true to continue the transfer, false to stop it