Subversive architecture

The main Subversive project's architecture points are:

• Separation of UI and Core parts
• Conceptual integrity of API
• Strong API levels delimitation
• API extensibility
• Unified error handling
• Fault tolerance

Core plug-in API has two levels to it - the high-level and the low-level APIs. First is the most frequently used one and it is based on the low-level API.

The High-level API consists of the following parts:

• Command Framework, which is designed accordingly to the "Command Pattern" concept. It allows to construct a complex workflows, covering interaction between SVN and Eclipse, in simple and understandable way. Moreover, we do provide a set of the basic construction blocks, the so-called «Operations», which covers most of the Subversion functionality and allows to build your own integration easy way. All the provided commands can be fully reused by external tools without limitations.
• SVN Resource Model allows to build a local and remote resource hierarchies and provides the command framework with all required information in a uniform way.
• Error Handling the mechanism that allows to build an application with high fault tolerance. It covers everything, from the initialization time and to the runtime errors. There is a way to ensure your commands are executed to the utmost possible level and with accordance to the workflow's inner dependencies.
• Execution Framework the code to run all the commands in a uniform way. Automatically handles resources locking rules and background jobs.
• Execution Engine API is a set of classes and interfaces that integrates all the functionality together.

The Low-level API allows to build Command Framework extensions in order to handle some rarely used or application-specific cases.

The Subversive UI extends Command and Execution Frameworks with UI specific features most of which can be reused by dependent projects. Additionally Subversive UI provides powerful and flexible Data Validation Framework for dialogs and wizards. The existing extension points allow reorganizing the Subversive UI functionality where it is of importance. For example the "Error Reporting" extension point allows to redirect bug reporting into application specific mailing list, while "Commit" extension point allows to customize commit workflow, used by plug-in by default.

UI plug-in extends Core functionality with several UI-specific features:

• UI Execution Extensions: enhances error handling in order to distinguish errors by severity, shows errors to user and proposes sending of bug reports to plug-in developers, connects progress monitoring to Eclipse Platform UI.
• UI Command Extensions include commands that are required to interact with the Eclipse Platform UI.

The Subversive architecture overview shows how the project structure conform to requirements. Both of the modules - Core and UI - are separate entities and the core module is fully functional on its own, so it can be used in order to build automated applications. Unified error handling mechanisms improves the Subversive project's fault tolerance. API concept allows to extend plug-in functionality easily with the least amount of work required.

On the following picture you can see the flow of calls that is required in order to update resources to the latest revision in a background thread. And next are "Code Sample 1" and "Code Sample 2" - both are the samples of how it looks in the code.

public class UpdateAction extends AbstractRecursiveTeamAction {
	public UpdateAction() {
		super();
	}

	public void runImpl(IAction action) {
		IResource []resources = this.getSelectedResources(IStateFilter.SF_ONREPOSITORY);
		if (resources == null || resources.length == 0) {
			return;
		}
		
		this.runScheduled(UpdateAction.getUpdateOperation(resources, SVNRevision.HEAD));
	}
	
	public boolean isEnabled() {
		return this.checkForResourcesPresence(IStateFilter.SF_ONREPOSITORY);
	}
	
	public static CompositeOperation getUpdateOperation(IResource []updateSet, SVNRevision selectedRevision) {
		boolean ignoreExternals = SVNTeamPreferences.getBehaviourBoolean(SVNTeamUIPlugin.instance().getPreferenceStore(), SVNTeamPreferences.BEHAVIOUR_IGNORE_EXTERNALS_NAME);
		UpdateOperation mainOp = new UpdateOperation(updateSet, selectedRevision, ignoreExternals);
		
		CompositeOperation op = new CompositeOperation(mainOp.getId(), mainOp.getMessagesClass());
		
		op.add(mainOp);
		op.add(new ClearUpdateStatusesOperation(mainOp), new IActionOperation[] {mainOp});
		op.add(new RefreshResourcesOperation(mainOp));
		op.add(new NotifyUnresolvedConflictOperation(mainOp));
		
		return op;
	}
	
	protected boolean needsToSaveDirtyEditors() {
		return true;
	}
	
}

In general case it is not required for programmers to implement their own commands and work with the SVN Client library's API. Nevertheless the task could be completed easily and in order to do so we do provide the low-level API which covers SVN functionality and hides the differences introduced by SVN API versions. Also, the implementation process requires programmer to take no further actions in order to ensure the files are locked, errors are properly handled and so on. The only requirement is to free all of the allocated resources in the "finally" section.

public class MarkResolvedOperation extends AbstractWorkingCopyOperation {
	protected SVNConflictResolution.Choice conflictResult;
	protected SVNDepth depth;
	
	public MarkResolvedOperation(IResource[] resources, SVNConflictResolution.Choice conflictResult, SVNDepth depth) {
		super("Operation_MarkResolved", SVNMessages.class, resources); //$NON-NLS-1$
		this.conflictResult = conflictResult;
		this.depth = depth;
	}

	public MarkResolvedOperation(IResourceProvider provider, SVNConflictResolution.Choice conflictResult, SVNDepth depth) {
		super("Operation_MarkResolved", SVNMessages.class, provider); //$NON-NLS-1$
		this.conflictResult = conflictResult;
		this.depth = depth;
	}

	protected void runImpl(IProgressMonitor monitor) throws Exception {
		IResource []resources = this.operableData();
		
		for (int i = 0; i < resources.length && !monitor.isCanceled(); i++) {
			IRepositoryLocation location = SVNRemoteStorage.instance().getRepositoryLocation(resources[i]);
			final String path = FileUtility.getWorkingCopyPath(resources[i]);
			final ISVNConnector proxy = location.acquireSVNProxy();
			
			this.protectStep(new IUnprotectedOperation() {
				public void run(IProgressMonitor monitor) throws Exception {
					proxy.resolve(path, MarkResolvedOperation.this.conflictResult, MarkResolvedOperation.this.depth, new SVNProgressMonitor(MarkResolvedOperation.this, monitor, null));
				}
			}, monitor, resources.length);
			
			location.releaseSVNProxy(proxy);
		}
	}

}

The Command Framework totally contains 87 commands which are presents in three subsets:

• Execution Framework Part (2)
• Core Command Framework (59)
• UI Command Extensions (16)

The core commands covers all the SVN functionality used in Subversive and they can be fully reused without any restrictions. At the same time most of the UI commands are designed for interactive usage, so they cannot be used in automated processing.