From 71b34847299f0c8f6923fe37fdd509f57fd35830 Mon Sep 17 00:00:00 2001
From: "Shawn O. Pearce" <spearce@spearce.org>
Date: Tue, 6 Oct 2009 20:09:29 -0700
Subject: [PATCH] Expose PacketLineOut for reuse outside of the transport
 package

Change-Id: Iaa331a476e28cf2880df5607de36bc9f67d041df
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
---
 .../eclipse/jgit/transport/PacketLineOut.java | 73 +++++++++++++++++--
 .../eclipse/jgit/transport/RefAdvertiser.java | 11 ++-
 2 files changed, 74 insertions(+), 10 deletions(-)

diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PacketLineOut.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PacketLineOut.java
index e7a7198d7..81dd4f6a1 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/PacketLineOut.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/PacketLineOut.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2008, Google Inc.
+ * Copyright (C) 2008-2009, Google Inc.
  * Copyright (C) 2008-2009, Robin Rosenberg <robin.rosenberg@dewire.com>
  * Copyright (C) 2008, Shawn O. Pearce <spearce@spearce.org>
  * and other copyright owners as documented in the project's IP log.
@@ -50,21 +50,56 @@ import java.io.OutputStream;
 
 import org.eclipse.jgit.lib.Constants;
 
-class PacketLineOut {
+/**
+ * Write Git style pkt-line formatting to an output stream.
+ * <p>
+ * This class is not thread safe and may issue multiple writes to the underlying
+ * stream for each method call made.
+ * <p>
+ * This class performs no buffering on its own. This makes it suitable to
+ * interleave writes performed by this class with writes performed directly
+ * against the underlying OutputStream.
+ */
+public class PacketLineOut {
 	private final OutputStream out;
 
 	private final byte[] lenbuffer;
 
-	PacketLineOut(final OutputStream i) {
-		out = i;
+	/**
+	 * Create a new packet line writer.
+	 *
+	 * @param outputStream
+	 *            stream.
+	 */
+	public PacketLineOut(final OutputStream outputStream) {
+		out = outputStream;
 		lenbuffer = new byte[5];
 	}
 
-	void writeString(final String s) throws IOException {
+	/**
+	 * Write a UTF-8 encoded string as a single length-delimited packet.
+	 *
+	 * @param s
+	 *            string to write.
+	 * @throws IOException
+	 *             the packet could not be written, the stream is corrupted as
+	 *             the packet may have been only partially written.
+	 */
+	public void writeString(final String s) throws IOException {
 		writePacket(Constants.encode(s));
 	}
 
-	void writePacket(final byte[] packet) throws IOException {
+	/**
+	 * Write a binary packet to the stream.
+	 *
+	 * @param packet
+	 *            the packet to write; the length of the packet is equal to the
+	 *            size of the byte array.
+	 * @throws IOException
+	 *             the packet could not be written, the stream is corrupted as
+	 *             the packet may have been only partially written.
+	 */
+	public void writePacket(final byte[] packet) throws IOException {
 		formatLength(packet.length + 4);
 		out.write(lenbuffer, 0, 4);
 		out.write(packet);
@@ -78,13 +113,35 @@ class PacketLineOut {
 		out.write(buf, off, len);
 	}
 
-	void end() throws IOException {
+	/**
+	 * Write a packet end marker, sometimes referred to as a flush command.
+	 * <p>
+	 * Technically this is a magical packet type which can be detected
+	 * separately from an empty string or an empty packet.
+	 * <p>
+	 * Implicitly performs a flush on the underlying OutputStream to ensure the
+	 * peer will receive all data written thus far.
+	 *
+	 * @throws IOException
+	 *             the end marker could not be written, the stream is corrupted
+	 *             as the end marker may have been only partially written.
+	 */
+	public void end() throws IOException {
 		formatLength(0);
 		out.write(lenbuffer, 0, 4);
 		flush();
 	}
 
-	void flush() throws IOException {
+	/**
+	 * Flush the underlying OutputStream.
+	 * <p>
+	 * Performs a flush on the underlying OutputStream to ensure the peer will
+	 * receive all data written thus far.
+	 *
+	 * @throws IOException
+	 *             the underlying stream failed to flush.
+	 */
+	public void flush() throws IOException {
 		out.flush();
 	}
 
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefAdvertiser.java b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefAdvertiser.java
index 2a06ed889..953fae918 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefAdvertiser.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/transport/RefAdvertiser.java
@@ -62,10 +62,17 @@ import org.eclipse.jgit.revwalk.RevWalk;
 
 /** Support for the start of {@link UploadPack} and {@link ReceivePack}. */
 public abstract class RefAdvertiser {
-	static class PacketLineOutRefAdvertiser extends RefAdvertiser {
+	/** Advertiser which frames lines in a {@link PacketLineOut} format. */
+	public static class PacketLineOutRefAdvertiser extends RefAdvertiser {
 		private final PacketLineOut pckOut;
 
-		PacketLineOutRefAdvertiser(PacketLineOut out) {
+		/**
+		 * Create a new advertiser for the supplied stream.
+		 *
+		 * @param out
+		 *            the output stream.
+		 */
+		public PacketLineOutRefAdvertiser(PacketLineOut out) {
 			pckOut = out;
 		}