1 /*
2 * Copyright (C) 2008, Marek Zawirski <marek.zawirski@gmail.com>
3 * Copyright (C) 2008, Shawn O. Pearce <spearce@spearce.org>
4 * and other copyright owners as documented in the project's IP log.
5 *
6 * This program and the accompanying materials are made available
7 * under the terms of the Eclipse Distribution License v1.0 which
8 * accompanies this distribution, is reproduced below, and is
9 * available at http://www.eclipse.org/org/documents/edl-v10.php
10 *
11 * All rights reserved.
12 *
13 * Redistribution and use in source and binary forms, with or
14 * without modification, are permitted provided that the following
15 * conditions are met:
16 *
17 * - Redistributions of source code must retain the above copyright
18 * notice, this list of conditions and the following disclaimer.
19 *
20 * - Redistributions in binary form must reproduce the above
21 * copyright notice, this list of conditions and the following
22 * disclaimer in the documentation and/or other materials provided
23 * with the distribution.
24 *
25 * - Neither the name of the Eclipse Foundation, Inc. nor the
26 * names of its contributors may be used to endorse or promote
27 * products derived from this software without specific prior
28 * written permission.
29 *
30 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
31 * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
32 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
33 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
34 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
35 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
36 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
37 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
38 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
39 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
40 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
41 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
42 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
43 */
44
45 package org.eclipse.jgit.transport;
46
47 import java.io.OutputStream;
48 import java.util.Map;
49
50 import org.eclipse.jgit.errors.TransportException;
51 import org.eclipse.jgit.lib.ProgressMonitor;
52
53 /**
54 * Lists known refs from the remote and sends objects to the remote.
55 * <p>
56 * A push connection typically connects to the <code>git-receive-pack</code>
57 * service running where the remote repository is stored. This provides a
58 * one-way object transfer service to copy objects from the local repository
59 * into the remote repository, as well as a way to modify the refs stored by the
60 * remote repository.
61 * <p>
62 * Instances of a PushConnection must be created by a
63 * {@link org.eclipse.jgit.transport.Transport} that implements a specific
64 * object transfer protocol that both sides of the connection understand.
65 * <p>
66 * PushConnection instances are not thread safe and may be accessed by only one
67 * thread at a time.
68 *
69 * @see Transport
70 */
71 public interface PushConnection extends Connection {
72
73 /**
74 * Pushes to the remote repository basing on provided specification. This
75 * possibly result in update/creation/deletion of refs on remote repository
76 * and sending objects that remote repository need to have a consistent
77 * objects graph from new refs.
78 * <p>
79 * <p>
80 * Only one call per connection is allowed. Subsequent calls will result in
81 * {@link org.eclipse.jgit.errors.TransportException}.
82 * </p>
83 * <p>
84 * Implementation may use local repository to send a minimum set of objects
85 * needed by remote repository in efficient way.
86 * {@link org.eclipse.jgit.transport.Transport#isPushThin()} should be
87 * honored if applicable. refUpdates should be filled with information about
88 * status of each update.
89 * </p>
90 *
91 * @param monitor
92 * progress monitor to update the end-user about the amount of
93 * work completed, or to indicate cancellation. Implementors
94 * should poll the monitor at regular intervals to look for
95 * cancellation requests from the user.
96 * @param refUpdates
97 * map of remote refnames to remote refs update
98 * specifications/statuses. Can't be empty. This indicate what
99 * refs caller want to update on remote side. Only refs updates
100 * with
101 * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED}
102 * should passed. Implementation must ensure that and appropriate
103 * status with optional message should be set during call. No
104 * refUpdate with
105 * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#AWAITING_REPORT}
106 * or
107 * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED}
108 * can be leaved by implementation after return from this call.
109 * @throws org.eclipse.jgit.errors.TransportException
110 * objects could not be copied due to a network failure,
111 * critical protocol error, or error on remote side, or
112 * connection was already used for push - new connection must be
113 * created. Non-critical errors concerning only isolated refs
114 * should be placed in refUpdates.
115 */
116 void push(final ProgressMonitor monitor,
117 final Map<String, RemoteRefUpdate> refUpdates)
118 throws TransportException;
119
120 /**
121 * Pushes to the remote repository basing on provided specification. This
122 * possibly result in update/creation/deletion of refs on remote repository
123 * and sending objects that remote repository need to have a consistent
124 * objects graph from new refs.
125 * <p>
126 * <p>
127 * Only one call per connection is allowed. Subsequent calls will result in
128 * {@link org.eclipse.jgit.errors.TransportException}.
129 * </p>
130 * <p>
131 * Implementation may use local repository to send a minimum set of objects
132 * needed by remote repository in efficient way.
133 * {@link org.eclipse.jgit.transport.Transport#isPushThin()} should be
134 * honored if applicable. refUpdates should be filled with information about
135 * status of each update.
136 * </p>
137 *
138 * @param monitor
139 * progress monitor to update the end-user about the amount of
140 * work completed, or to indicate cancellation. Implementors
141 * should poll the monitor at regular intervals to look for
142 * cancellation requests from the user.
143 * @param refUpdates
144 * map of remote refnames to remote refs update
145 * specifications/statuses. Can't be empty. This indicate what
146 * refs caller want to update on remote side. Only refs updates
147 * with
148 * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED}
149 * should passed. Implementation must ensure that and appropriate
150 * status with optional message should be set during call. No
151 * refUpdate with
152 * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#AWAITING_REPORT}
153 * or
154 * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED}
155 * can be leaved by implementation after return from this call.
156 * @param out
157 * output stream to write sideband messages to
158 * @throws org.eclipse.jgit.errors.TransportException
159 * objects could not be copied due to a network failure,
160 * critical protocol error, or error on remote side, or
161 * connection was already used for push - new connection must be
162 * created. Non-critical errors concerning only isolated refs
163 * should be placed in refUpdates.
164 * @since 3.0
165 */
166 void push(final ProgressMonitor monitor,
167 final Map<String, RemoteRefUpdate> refUpdates, OutputStream out)
168 throws TransportException;
169
170 }