Package-level Javadoc
Author: IBM

Contains the team synchronization presentation framework and support for the Synchronize View.

## Package Specification

Contains the team synchronization presentation framework and support for the Synchronize View. A synchronization framework is a unified architecture for presenting and manipulating resource synchronization state. Consider the synchronization model described by the classes in `org.eclipse.team.core.synchronize` as the physical representation of synchronization state then the classes in this package allow you to control how the model is presented to the user. This framework doesn't attempt to provide common operations for manipulating synchronization state. Instead it is left up to the framework user to add their own domain specific operations to the presentation.

The primary advantages of this synchronization presentation framework are that it:

- Provides a unified synchronization experience in the workbench. It makes it easier to present one synchronization story to the user across multiple tools that synchronize resources. This includes access to the Synchronize View, the Team Synchronizing Perspective, the global Synchronize Action, Synchronize dialogs, and compare editors.
- Reduces the effort required to learn other APIs by eliminating the need to learn many workbench APIs to enable this rich support.
- Fosters software re-use by allowing multiple repository providers and other tools to enable rich integration without the initial cost of learning how to integrate into Eclipse.

The synchronization presentation framework consists of:

- Synchronize View Interfaces - Represents a set of classes and interfaces to support a generic synchronize view that can show multiple synchronize participants.
- SubscriberParticipants - Concrete implementation of the synchronize view interfaces for synchronizations that are SyncInfo based. Subclasses get the well-known synchronize page that supports 4 modes (e.g. incomming/outgoing/conficting/both) and the standard resource layouts (compressed folder and hierarchical). This is the easy entry point into the Synchronize View since all a client would have to provide is a Subscriber class that generates SyncInfo instances for resources and a set of operations that run on the sync nodes.
- Compare Inputs - These are helpers for allowing users to display and edit the resources being synchronized.
- Synchronize action and operation utilities - Represent helpers for writing actions that are performed on elements shown in synchronization viewers.

### Synchronize View Interfaces

These interfaces and classes support a generic Synchronize View that can show multiple synchronize participants. The basic model for integrating into the Synchronize View consists of:

- A ISynchronizeManager manages registered synchronize participants. Every participant has a type and and instance identifier.
- A ISynchronizeParticipant is a logical representation of a connection between workspace resources and a remote location used to shared those resources. A participant creates a page in that shows the synchronization for the participant.
- A ISynchronizeView is a page book view of participants. The synchronize view has support for showing multiple synchronizations. As described above, you will see merges, 2 way-compares, and basic synchronizations. Synchronizations are categorized into types, for example the CVS plugin defines three types: CVS, CVS Merge, and CVS Compare. You can switch between synchronizations using the drop-down menu in the sync view. When you create a new synchronization it will replace the first existing synchronization of the same type unless it is pinned. Pinning allows you to manage the synchronizations that are of interest to you and ensure that they remain easily accessible. This should provide for easy management of multiple synchronizations.
- A ISynchronizeParticipant must create a page that will be displayed in the ISynchronizeView page book view.
- The ISynchronizeView shows a drop-down of all registered participants and allows switching between them.
- A ISynchronizeParticipant creates a configuration which is used to configure the presentation of the participant by clients. For example, clients using a ISynchronizeParticipant instances can decide to show the participant page with a set of customized menus or toolbar actions.

Synchronize participants are declared by extending the synchronizeParticipants extension point. A synchronize manager manages all active synchronize participants, and provides notification of participants which are added and removed. Participants are displayed in a page book view. Each participant implementation is reponsible for creating its page, which provides freedom of presentation to the synchronize view implementation. A single participant may be displayed simultaneously in multiple synchronize views, and in different workbench windows.

### SubscriberParticipants

SubscriberParticipant is an abstract class that is intented to support a common synchronization workflow. It is the easy way to get into the Synchronize View and essentially inherit the default synchronize experience. The requirement for using a SubscriberParticipant is to create a subscriber that can produce SyncInfo (e.g. objects that describe the synchronization between local and remote resources).

### Compare Inputs

These are helpers for allowing users to display and edit resources being synchronized by integrating with the compare support available in Eclipse.

### Synchronize action and operation utilities

These are helpers for writing actions that are performed on elements shown in synchronize viewers.

### Related Documentation

- For examples of these APIs in action please see the org.eclipse.team.examples.filesystem plug-in example and also refer to the Platform Plug-in Developer Guide > Programmer's Guide > Team Support documentation.