Package org.eclipse.team.core

## Class ProjectSetCapability

- java.lang.Object
- - org.eclipse.team.core.ProjectSetCapability

    public abstract class ProjectSetCapability
    extends Object

An object for serializing and deserializing references to projects. Given a project, it can produce a UTF-8 encoded String which can be stored in a file. Given this String, it can load a project into the workspace. It also provides a mechanism by which repository providers can be notified when a project set is created and exported.

Since:
  2.1
See Also:
  `RepositoryProviderType`

### Field Summary

Fields
`static String` `SCHEME_SCM` Scheme constant (value "scm") indicating the SCM URI.

### Constructor Summary

Constructors
`ProjectSetCapability()`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
`IProject[]` `addToWorkspace​(String[] referenceStrings, ProjectSetSerializationContext context, IProgressMonitor monitor)` For every String in `referenceStrings`, load the corresponding project into the workspace.
`String` `asReference​(URI uri, String projectName)` Convert the given URI and projectName to a reference string that can be passed to the `addToWorkspace(String[], ProjectSetSerializationContext, IProgressMonitor)` method.
`String[]` `asReference​(IProject[] providerProjects, ProjectSetSerializationContext context, IProgressMonitor monitor)` For every project in providerProjects, return an opaque UTF-8 encoded String to act as a reference to that project.
`protected IProject[]` `confirmOverwrite​(ProjectSetSerializationContext context, IProject[] projects)` Determine if any of the projects already exist and confirm which of those projects are to be overwritten.
`static void` `ensureBackwardsCompatible​(RepositoryProviderType type, ProjectSetCapability capability)` Ensure that the provider type is backwards compatible by passing the project set serializer to the type if a serializer is registered.
`String` `getProject​(String referenceString)` Return the name of the project that is the target of the given reference string or `null` if this capability does not support parsing of reference strings.
`URI` `getURI​(String referenceString)` Return the URI for the given reference string or `null` if this capability does not support file system schemes as defined by the `org.eclipse.core.filesystem.filesystems` extension point.
`void` `projectSetCreated​(File file, Object context, IProgressMonitor monitor)` Deprecated. should use or override projectSetCreated(File, ProjectSetSerializationContext, IProgressMonitor) instead
`void` `projectSetCreated​(File file, ProjectSetSerializationContext context, IProgressMonitor monitor)` Notify the provider that a project set has been created at path.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### SCHEME_SCM

    public static final String SCHEME_SCM

Scheme constant (value "scm") indicating the SCM URI.

Since:
  3.6
See Also:
  Constant Field Values

### Constructor Detail

#### ProjectSetCapability

    public ProjectSetCapability()

### Method Detail

#### ensureBackwardsCompatible

    public static void ensureBackwardsCompatible​(RepositoryProviderType type,
                                                 ProjectSetCapability capability)

Ensure that the provider type is backwards compatible by passing the project set serializer to the type if a serializer is registered. This is required for repository providers who implemented a project set capability in 2.1 (before the capability contained the serialization API) and have not released a 3.0 plugin yet. This method is called before project set export and import and can be used by other clients who work with project sets.

Parameters:
  `type` - the provider type instance
  `capability` - the capability that was obtained from the provider type
Since:
  3.0

#### projectSetCreated

    @Deprecated
    public void projectSetCreated​(File file,
                                  Object context,
                                  IProgressMonitor monitor)

Deprecated.
should use or override projectSetCreated(File, ProjectSetSerializationContext, IProgressMonitor) instead
Notify the provider that a project set has been created at path. Only providers identified as having projects in the project set will be notified. The project set may or may not be created in a workspace project (thus may not be a resource).

Parameters:
  `file` - the project set file that was created
  `context` - a UI context object. This object will either be a com.ibm.swt.widgets.Shell or it will be null.
  `monitor` - a progress monitor

#### projectSetCreated

    public void projectSetCreated​(File file,
                                  ProjectSetSerializationContext context,
                                  IProgressMonitor monitor)

Notify the provider that a project set has been created at path. Only providers identified as having projects in the project set will be notified. The project set may or may not be created in a workspace project (thus may not be a resource).

Parameters:
  `file` - the project set file that was created
  `context` - the context in which the references are created (not `null`)
  `monitor` - a progress monitor
Since:
  3.0

#### asReference

    public String[] asReference​(IProject[] providerProjects,
                                ProjectSetSerializationContext context,
                                IProgressMonitor monitor)
                         throws TeamException

For every project in providerProjects, return an opaque UTF-8 encoded String to act as a reference to that project. The format of the String is specific to the provider. The format of the String must be such that `addToWorkspace(String[], ProjectSetSerializationContext, IProgressMonitor)` will be able to consume it and load the corresponding project.

This default implementation simply throws an exception indicating that no references can be created unless there is an IProjectSetSerializer registered for the repository provider type in which case the operation is delegated to the serializer. Subclasses are expected to override.

Parameters:
  `providerProjects` - an array of projects for which references are needed (not `null` and contains no `null`s)
  `context` - the context in which the references are created (not `null`)
  `monitor` - a progress monitor or `null` if none
Returns:
  an array containing exactly the same number of elements as the providerProjects argument where each element is a serialized reference string uniquely identifying the corresponding the project in the providerProjects array (not `null` and contains no `null`s)
Throws:
  `TeamException` - thrown if there is a reference string cannot be created for a project
Since:
  3.0

#### addToWorkspace

    public IProject[] addToWorkspace​(String[] referenceStrings,
                                     ProjectSetSerializationContext context,
                                     IProgressMonitor monitor)
                              throws TeamException

For every String in `referenceStrings`, load the corresponding project into the workspace. The opaque strings in `referenceStrings` are guaranteed to have been previously produced by `asReference(IProject[], ProjectSetSerializationContext, IProgressMonitor)`. The `confirmOverwrite(ProjectSetSerializationContext, IProject[])` method is called with an array of projects for which projects of the same name already exists in the workspace.

Callers from within a UI context should wrap a call to this method inside a `WorkspaceModifyOperation` so that events generated as a result of this operation are deferred until the outermost operation has successfully completed.

This default implementation simply throws an exception indicating that no projects can be loaded unless there is an `IProjectSetSerializer` registered for the repository provider type in which case the operation is delegated to the serializer. Subclasses are expected to override.

Parameters:
  `referenceStrings` - an array of reference strings uniquely identifying the projects (not `null` and contains no `null`s)
  `context` - the context in which the projects are loaded (not `null`)
  `monitor` - a progress monitor or `null` if none
Returns:
  IProject[] an array of projects that were loaded excluding those projects already existing and not overwritten (not `null`, contains no `null`s)
Throws:
  `TeamException` - thrown if there is a problem loading a project into the workspace. If an exception is thrown, then the workspace is left in an unspecified state where some of the referenced projects may be loaded or partially loaded, and others may not.
Since:
  3.0

#### confirmOverwrite

    protected IProject[] confirmOverwrite​(ProjectSetSerializationContext context,
                                          IProject[] projects)
                                   throws TeamException

Determine if any of the projects already exist and confirm which of those projects are to be overwritten.

Parameters:
  `context` - the context in which the projects are loaded (not `null`)
  `projects` - an array of proposed projects to be loaded (not `null`, contains no `null`s)
Returns:
  an array of confirmed projects to be loaded or `null` if the operation is to be canceled.
Throws:
  `TeamException`
Since:
  3.0

#### getURI

    public URI getURI​(String referenceString)

Return the URI for the given reference string or `null` if this capability does not support file system schemes as defined by the `org.eclipse.core.filesystem.filesystems` extension point.

Parameters:
  `referenceString` - a reference string obtained from `asReference(IProject[], ProjectSetSerializationContext, IProgressMonitor)`
Returns:
  the URI for the given reference string or `null`
Since:
  3.2
See Also:
  `getProject(String)`

#### getProject

    public String getProject​(String referenceString)

Return the name of the project that is the target of the given reference string or `null` if this capability does not support parsing of reference strings.

Parameters:
  `referenceString` - reference string obtained from `asReference(IProject[], ProjectSetSerializationContext, IProgressMonitor)`
Returns:
  the name of the project that is the target of the given reference string or `null`
Since:
  3.2
See Also:
  `getURI(String)`

#### asReference

    public String asReference​(URI uri,
                              String projectName)

Convert the given URI and projectName to a reference string that can be passed to the `addToWorkspace(String[], ProjectSetSerializationContext, IProgressMonitor)` method. The scheme of the provided URI must match the scheme of the repository provider type from which this capability was obtained.

Since 3.7 SCM URIs are also accepted.

The default implementation returns `null`. Subclasses may override.

Parameters:
  `uri` - the URI that identifies the location of the project in the repository.
  `projectName` - the name of the project to use. If `null`, use a project name from the provided SCM URI. If the URI does not contain the project name the last segment of the URI's path is used. If this fails, `null` is returned.
Returns:
  the reference string representing a project that can be loaded into the workspace or `null`, if the URI and name cannot be translated into a reference string
Since:
  3.2
See Also:
  `SCHEME_SCM`