1 /*
2 * Copyright (C) 2008, Marek Zawirski <marek.zawirski@gmail.com>
3 * Copyright (C) 2008, Shawn O. Pearce <spearce@spearce.org> and others
4 *
5 * This program and the accompanying materials are made available under the
6 * terms of the Eclipse Distribution License v. 1.0 which is available at
7 * https://www.eclipse.org/org/documents/edl-v10.php.
8 *
9 * SPDX-License-Identifier: BSD-3-Clause
10 */
11
12 package org.eclipse.jgit.transport;
13
14 import java.io.OutputStream;
15 import java.util.Map;
16
17 import org.eclipse.jgit.errors.TransportException;
18 import org.eclipse.jgit.lib.ProgressMonitor;
19
20 /**
21 * Lists known refs from the remote and sends objects to the remote.
22 * <p>
23 * A push connection typically connects to the <code>git-receive-pack</code>
24 * service running where the remote repository is stored. This provides a
25 * one-way object transfer service to copy objects from the local repository
26 * into the remote repository, as well as a way to modify the refs stored by the
27 * remote repository.
28 * <p>
29 * Instances of a PushConnection must be created by a
30 * {@link org.eclipse.jgit.transport.Transport} that implements a specific
31 * object transfer protocol that both sides of the connection understand.
32 * <p>
33 * PushConnection instances are not thread safe and may be accessed by only one
34 * thread at a time.
35 *
36 * @see Transport
37 */
38 public interface PushConnection extends Connection {
39
40 /**
41 * Pushes to the remote repository basing on provided specification. This
42 * possibly result in update/creation/deletion of refs on remote repository
43 * and sending objects that remote repository need to have a consistent
44 * objects graph from new refs.
45 * <p>
46 * <p>
47 * Only one call per connection is allowed. Subsequent calls will result in
48 * {@link org.eclipse.jgit.errors.TransportException}.
49 * </p>
50 * <p>
51 * Implementation may use local repository to send a minimum set of objects
52 * needed by remote repository in efficient way.
53 * {@link org.eclipse.jgit.transport.Transport#isPushThin()} should be
54 * honored if applicable. refUpdates should be filled with information about
55 * status of each update.
56 * </p>
57 *
58 * @param monitor
59 * progress monitor to update the end-user about the amount of
60 * work completed, or to indicate cancellation. Implementors
61 * should poll the monitor at regular intervals to look for
62 * cancellation requests from the user.
63 * @param refUpdates
64 * map of remote refnames to remote refs update
65 * specifications/statuses. Can't be empty. This indicate what
66 * refs caller want to update on remote side. Only refs updates
67 * with
68 * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED}
69 * should passed. Implementation must ensure that and appropriate
70 * status with optional message should be set during call. No
71 * refUpdate with
72 * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#AWAITING_REPORT}
73 * or
74 * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED}
75 * can be leaved by implementation after return from this call.
76 * @throws org.eclipse.jgit.errors.TransportException
77 * objects could not be copied due to a network failure,
78 * critical protocol error, or error on remote side, or
79 * connection was already used for push - new connection must be
80 * created. Non-critical errors concerning only isolated refs
81 * should be placed in refUpdates.
82 */
83 void push(final ProgressMonitor monitor,
84 final Map<String, RemoteRefUpdate> refUpdates)
85 throws TransportException;
86
87 /**
88 * Pushes to the remote repository basing on provided specification. This
89 * possibly result in update/creation/deletion of refs on remote repository
90 * and sending objects that remote repository need to have a consistent
91 * objects graph from new refs.
92 * <p>
93 * <p>
94 * Only one call per connection is allowed. Subsequent calls will result in
95 * {@link org.eclipse.jgit.errors.TransportException}.
96 * </p>
97 * <p>
98 * Implementation may use local repository to send a minimum set of objects
99 * needed by remote repository in efficient way.
100 * {@link org.eclipse.jgit.transport.Transport#isPushThin()} should be
101 * honored if applicable. refUpdates should be filled with information about
102 * status of each update.
103 * </p>
104 *
105 * @param monitor
106 * progress monitor to update the end-user about the amount of
107 * work completed, or to indicate cancellation. Implementors
108 * should poll the monitor at regular intervals to look for
109 * cancellation requests from the user.
110 * @param refUpdates
111 * map of remote refnames to remote refs update
112 * specifications/statuses. Can't be empty. This indicate what
113 * refs caller want to update on remote side. Only refs updates
114 * with
115 * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED}
116 * should passed. Implementation must ensure that and appropriate
117 * status with optional message should be set during call. No
118 * refUpdate with
119 * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#AWAITING_REPORT}
120 * or
121 * {@link org.eclipse.jgit.transport.RemoteRefUpdate.Status#NOT_ATTEMPTED}
122 * can be leaved by implementation after return from this call.
123 * @param out
124 * output stream to write sideband messages to
125 * @throws org.eclipse.jgit.errors.TransportException
126 * objects could not be copied due to a network failure,
127 * critical protocol error, or error on remote side, or
128 * connection was already used for push - new connection must be
129 * created. Non-critical errors concerning only isolated refs
130 * should be placed in refUpdates.
131 * @since 3.0
132 */
133 void push(final ProgressMonitor monitor,
134 final Map<String, RemoteRefUpdate> refUpdates, OutputStream out)
135 throws TransportException;
136
137 }