ISynchronizer


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.core.resources;
12  
13  import org.eclipse.core.runtime.CoreException;
14  import org.eclipse.core.runtime.QualifiedName;
15  
16  /**
17   * A synchronizer which maintains a list of registered partners and, on behalf of
18   * each partner, it keeps resource level synchronization information 
19   * (a byte array). Sync info is saved only when the workspace is saved.
20   * <p>
21   * This interface is not intended to be implemented by clients.
22   * </p>
23   * @see IWorkspace#getSynchronizer()
24   */
25  public interface ISynchronizer {
26      /**
27       * Visits the given resource and its descendents with the specified visitor
28       * if sync information for the given sync partner is found on the resource. If
29       * sync information for the given sync partner is not found on the resource,
30       * still visit the children of the resource if the depth specifies to do so.
31       *
32       * @param partner the sync partner name
33       * @param start the parent resource to start the visitation
34       * @param visitor the visitor to use when visiting the resources
35       * @param depth the depth to which members of this resource should be
36       *      visited.  One of <code>IResource.DEPTH_ZERO</code>, <code>IResource.DEPTH_ONE</code>,
37       *      or <code>IResource.DEPTH_INFINITE</code>.
38       * @exception CoreException if this operation fails. Reasons include:
39       *    <ul>
40       *    <li>The resource does not exist.</li>
41       *    <li><code>IResourceStatus.PARTNER_NOT_REGISTERED</code> 
42       The sync partner is not registered.</li>
43       *    </ul>
44       */
45      public void accept(QualifiedName partner, IResource start, IResourceVisitor visitor, int depth) throws CoreException;
46  
47      /**
48       * Adds the named synchronization partner to this synchronizer's
49       * registry of partners. Once a partner's name has been registered, sync
50       * information can be set and retrieve on resources relative to the name.
51       * Adding a sync partner multiple times has no effect.
52       *
53       * @param partner the partner name to register
54       * @see #remove(QualifiedName)
55       */
56      public void add(QualifiedName partner);
57  
58      /**
59       * Discards the named partner's synchronization information 
60       * associated with the specified resource and its descendents to the
61       * specified depth. 
62       *
63       * @param partner the sync partner name
64       * @param resource the resource
65       * @param depth the depth to which members of this resource should be
66       *      visited.  One of <code>IResource.DEPTH_ZERO</code>, <code>IResource.DEPTH_ONE</code>,
67       *      or <code>IResource.DEPTH_INFINITE</code>.
68       * @exception CoreException if this operation fails. Reasons include:
69       *    <ul>
70       *    <li>The resource does not exist.</li>
71       *    <li><code>IResourceStatus.PARTNER_NOT_REGISTERED</code> 
72       The sync partner is not registered.</li>
73       *    </ul>
74       */
75      public void flushSyncInfo(QualifiedName partner, IResource resource, int depth) throws CoreException;
76  
77      /**
78       * Returns a list of synchronization partner names currently registered
79       * with this synchronizer. Returns an empty array if there are no
80       * registered sync partners.
81       *
82       * @return a list of sync partner names
83       */
84      public QualifiedName[] getPartners();
85  
86      /**
87       * Returns the named sync partner's synchronization information for the given resource.
88       * Returns <code>null</code> if no information is found.
89       *
90       * @param partner the sync partner name
91       * @param resource the resource
92       * @return the synchronization information, or <code>null</code> if none
93       * @exception CoreException if this operation fails. Reasons include:
94       *    <ul>
95       *    <li><code>IResourceStatus.PARTNER_NOT_REGISTERED</code> 
96       The sync partner is not registered.</li>
97       *    </ul>
98       */
99      public byte[] getSyncInfo(QualifiedName partner, IResource resource) throws CoreException;
100 
101     /**
102      * Removes the named synchronization partner from this synchronizer's
103      * registry.  Does nothing if the partner is not registered.
104      * This discards all sync information for the defunct partner.
105      * After a partner has been unregistered, sync information for it can no 
106      * longer be stored on resources.
107      *
108      * @param partner the partner name to remove from the registry
109      * @see #add(QualifiedName)
110      */
111     public void remove(QualifiedName partner);
112 
113     /**
114      * Sets the named sync partner's synchronization information for the given resource.
115      * If the given info is non-<code>null</code> and the resource neither exists
116      * nor is a phantom, this method creates a phantom resource to hang on to the info.
117      * If the given info is <code>null</code>, any sync info for the resource stored by the
118      * given sync partner is discarded; in some cases, this may result in the deletion
119      * of a phantom resource if there is no more sync info to maintain for that resource.
120      * <p>
121      * Sync information is not stored on the workspace root. Attempts to set information
122      * on the root will be ignored.
123      * </p>
124      *
125      * @param partner the sync partner name
126      * @param resource the resource
127      * @param info the synchronization information, or <code>null</code>
128      * @exception CoreException if this operation fails. Reasons include:
129      *    <ul>
130      *    <li><code>IResourceStatus.PARTNER_NOT_REGISTERED</code> 
131      The sync partner is not registered.</li>
132      *    </ul>
133      */
134     public void setSyncInfo(QualifiedName partner, IResource resource, byte[] info) throws CoreException;
135 }
136
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags