From 1ad9579e6e61918f8a78a4cc8070fe9524e590af Mon Sep 17 00:00:00 2001 From: Trustin Lee Date: Tue, 26 Jan 2010 06:31:25 +0000 Subject: [PATCH] Javadoc for the RTSP package --- .../netty/handler/codec/rtsp/RtspHeaders.java | 141 ++++++++++++++++-- .../netty/handler/codec/rtsp/RtspMethod.java | 87 ++++++++--- .../codec/rtsp/RtspRequestDecoder.java | 15 ++ .../codec/rtsp/RtspResponseDecoder.java | 15 ++ .../codec/rtsp/RtspResponseStatus.java | 13 ++ .../netty/handler/codec/rtsp/RtspVersion.java | 33 +++- .../handler/codec/rtsp/package-info.java | 21 +++ 7 files changed, 281 insertions(+), 44 deletions(-) create mode 100644 src/main/java/org/jboss/netty/handler/codec/rtsp/package-info.java diff --git a/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspHeaders.java b/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspHeaders.java index d8669b86cd..22d3e83abb 100644 --- a/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspHeaders.java +++ b/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspHeaders.java @@ -18,6 +18,7 @@ package org.jboss.netty.handler.codec.rtsp; import org.jboss.netty.handler.codec.http.HttpHeaders; /** + * Standard RTSP header names and values. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Amit Bhayani (amit.bhayani@gmail.com) @@ -26,36 +27,74 @@ import org.jboss.netty.handler.codec.http.HttpHeaders; */ public class RtspHeaders { + /** + * Standard RTSP header names. + * + * @author The Netty Project (netty-dev@lists.jboss.org) + * @author Amit Bhayani (amit.bhayani@gmail.com) + * @author Trustin Lee (trustin@gmail.com) + * @version $Rev$, $Date$ + */ public static class Names extends HttpHeaders.Names { - + /** + * {@code "Allow"} + */ public static final String ALLOW = "Allow"; - + /** + * {@code "Bandwidth"} + */ public static final String BANDWIDTH = "Bandwidth"; - + /** + * {@code "Blocksize"} + */ public static final String BLOCKSIZE = "Blocksize"; - + /** + * {@code "Conference"} + */ public static final String CONFERENCE = "Conference"; - + /** + * {@code "CSeq"} + */ public static final String CSEQ = "CSeq"; - + /** + * {@code "Proxy-Require"} + */ public static final String PROXY_REQUIRE = "Proxy-Require"; - + /** + * {@code "Public"} + */ public static final String PUBLIC = "Public"; - + /** + * {@code "Require"} + */ public static final String REQUIRE = "Require"; - + /** + * {@code "RTP-Info"} + */ public static final String RTP_INFO = "RTP-Info"; - + /** + * {@code "Scale"} + */ public static final String SCALE = "Scale"; - + /** + * {@code "Speed"} + */ public static final String SPEED = "Speed"; - + /** + * {@code "Session"} + */ public static final String SESSION = "Session"; - + /** + * {@code "Timestamp"} + */ public static final String TIMESTAMP = "Timestamp"; - + /** + * {@code "Transport"} + */ public static final String TRANSPORT = "Transport"; - + /** + * {@code "Unsupported"} + */ public static final String UNSUPPORTED = "Unsupported"; protected Names() { @@ -63,31 +102,101 @@ public class RtspHeaders { } } + /** + * Standard RTSP header names. + * + * @author The Netty Project (netty-dev@lists.jboss.org) + * @author Trustin Lee (trustin@gmail.com) + * @version $Rev$, $Date$ + */ public static class Values extends HttpHeaders.Values { - + /** + * {@code "append"} + */ public static final String APPEND = "append"; + /** + * {@code "AVP"} + */ public static final String AVP = "AVP"; + /** + * {@code "client_port"} + */ public static final String CLIENT_PORT = "client_port"; + /** + * {@code "destination"} + */ public static final String DESTINATION = "destination"; + /** + * {@code "interleaved"} + */ public static final String INTERLEAVED = "interleaved"; + /** + * {@code "layers"} + */ public static final String LAYERS = "layers"; + /** + * {@code "mode"} + */ public static final String MODE = "mode"; + /** + * {@code "multicast"} + */ public static final String MULTICAST = "multicast"; + /** + * {@code "port"} + */ public static final String PORT = "port"; + /** + * {@code "RTP"} + */ public static final String RTP = "RTP"; + /** + * {@code "rtptime"} + */ public static final String RTPTIME = "rtptime"; + /** + * {@code "seq"} + */ public static final String SEQ = "seq"; + /** + * {@code "server_port"} + */ public static final String SERVER_PORT = "server_port"; + /** + * {@code "ssrc"} + */ public static final String SSRC = "ssrc"; + /** + * {@code "TCP"} + */ public static final String TCP = "TCP"; + /** + * {@code "timeout"} + */ public static final String TIMEOUT = "timeout"; + /** + * {@code "ttl"} + */ public static final String TTL = "ttl"; + /** + * {@code "UDP"} + */ public static final String UDP = "UDP"; + /** + * {@code "unicast"} + */ public static final String UNICAST = "unicast"; + /** + * {@code "url"} + */ public static final String URL = "url"; protected Values() { super(); } } + + protected RtspHeaders() { + super(); + } } diff --git a/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspMethod.java b/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspMethod.java index f786f58d75..3c9f94d4d5 100644 --- a/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspMethod.java +++ b/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspMethod.java @@ -21,6 +21,7 @@ import java.util.Map; import org.jboss.netty.handler.codec.http.HttpMethod; /** + * The request method of RTSP. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Amit Bhayani (amit.bhayani@gmail.com) @@ -29,31 +30,68 @@ import org.jboss.netty.handler.codec.http.HttpMethod; */ public class RtspMethod extends HttpMethod { + /** + * The DESCRIBE method retrieves the description of a presentation or + * media object identified by the request URL from a server. + */ public static final RtspMethod DESCRIBE = new RtspMethod("DESCRIBE"); + /** + * The ANNOUNCE posts the description of a presentation or media object + * identified by the request URL to a server, or updates the client-side + * session description in real-time. + */ public static final RtspMethod ANNOUNCE = new RtspMethod("ANNOUNCE"); - public static final RtspMethod GET_PARAMETER = new RtspMethod( - "GET_PARAMETER"); - - public static final RtspMethod OPTIONS = new RtspMethod("OPTIONS"); - - public static final RtspMethod PAUSE = new RtspMethod("PAUSE"); - - public static final RtspMethod PLAY = new RtspMethod("PLAY"); - - public static final RtspMethod RECORD = new RtspMethod("RECORD"); - - public static final RtspMethod REDIRECT = new RtspMethod("REDIRECT"); - + /** + * The SETUP request for a URI specifies the transport mechanism to be + * used for the streamed media. + */ public static final RtspMethod SETUP = new RtspMethod("SETUP"); - public static final RtspMethod SET_PARAMETER = new RtspMethod( - "SET_PARAMETER"); + /** + * The PLAY method tells the server to start sending data via the + * mechanism specified in SETUP. + */ + public static final RtspMethod PLAY = new RtspMethod("PLAY"); + /** + * The PAUSE request causes the stream delivery to be interrupted + * (halted) temporarily. + */ + public static final RtspMethod PAUSE = new RtspMethod("PAUSE"); + + /** + * The TEARDOWN request stops the stream delivery for the given URI, + * freeing the resources associated with it. + */ public static final RtspMethod TEARDOWN = new RtspMethod("TEARDOWN"); - private static final Map methodMap = new HashMap(); + /** + * The GET_PARAMETER request retrieves the value of a parameter of a + * presentation or stream specified in the URI. + */ + public static final RtspMethod GET_PARAMETER = new RtspMethod("GET_PARAMETER"); + + /** + * The SET_PARAMETER requests to set the value of a parameter for a + * presentation or stream specified by the URI. + */ + public static final RtspMethod SET_PARAMETER = new RtspMethod("SET_PARAMETER"); + + /** + * The REDIRECT request informs the client that it must connect to another + * server location. + */ + public static final RtspMethod REDIRECT = new RtspMethod("REDIRECT"); + + /** + * The RECORD method initiates recording a range of media data according to + * the presentation description. + */ + public static final RtspMethod RECORD = new RtspMethod("RECORD"); + + private static final Map methodMap = new HashMap(); static { methodMap.put(DESCRIBE.toString(), DESCRIBE); @@ -67,15 +105,24 @@ public class RtspMethod extends HttpMethod { methodMap.put(SETUP.toString(), SETUP); methodMap.put(SET_PARAMETER.toString(), SET_PARAMETER); methodMap.put(TEARDOWN.toString(), TEARDOWN); - } + /** + * Creates a new RTSP method with the specified name. + */ public RtspMethod(String name) { super(name); } - public static RtspMethod valueOf(String name) { - + /** + * Returns the {@link HttpMethod} represented by the specified name. + * If the specified name is a standard RTSP method name, a cached instance + * will be returned. Otherwise, a new instance will be returned. + * Please note that this method does not return {@link RtspMethod} but + * returns {@link HttpMethod} because the RTSP re-uses some HTTP methods + * in its specification. + */ + public static HttpMethod valueOf(String name) { if (name == null) { throw new NullPointerException("name"); } @@ -85,7 +132,7 @@ public class RtspMethod extends HttpMethod { throw new IllegalArgumentException("empty name"); } - RtspMethod result = methodMap.get(name); + HttpMethod result = methodMap.get(name); if (result != null) { return result; } else { diff --git a/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspRequestDecoder.java b/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspRequestDecoder.java index f544985376..cd25c6c75a 100644 --- a/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspRequestDecoder.java +++ b/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspRequestDecoder.java @@ -15,11 +15,18 @@ */ package org.jboss.netty.handler.codec.rtsp; +import org.jboss.netty.buffer.ChannelBuffer; import org.jboss.netty.handler.codec.http.DefaultHttpRequest; import org.jboss.netty.handler.codec.http.HttpMessage; import org.jboss.netty.handler.codec.http.HttpMessageDecoder; +import org.jboss.netty.handler.codec.http.HttpRequest; /** + * Decodes {@link ChannelBuffer}s into {@link HttpRequest}s whose method is + * {@link RtspMethod} and protocol version is {@link RtspVersion}. + *

+ * Please refer to {@link HttpMessageDecoder} for the detailed information on + * how this decoder works and what parameters are available. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Amit Bhayani (amit.bhayani@gmail.com) @@ -28,10 +35,18 @@ import org.jboss.netty.handler.codec.http.HttpMessageDecoder; */ public class RtspRequestDecoder extends HttpMessageDecoder { + /** + * Creates a new instance with the default + * {@code maxInitialLineLength (4096}}, {@code maxHeaderSize (4096)}, and + * {@code maxChunkSize (4096)}. + */ public RtspRequestDecoder() { super(); } + /** + * Creates a new instance with the specified parameters. + */ public RtspRequestDecoder(int maxInitialLineLength, int maxHeaderSize, int maxChunkSize) { super(maxInitialLineLength, maxHeaderSize, maxChunkSize); diff --git a/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspResponseDecoder.java b/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspResponseDecoder.java index 683ee053bc..4534a20d57 100644 --- a/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspResponseDecoder.java +++ b/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspResponseDecoder.java @@ -15,11 +15,18 @@ */ package org.jboss.netty.handler.codec.rtsp; +import org.jboss.netty.buffer.ChannelBuffer; import org.jboss.netty.handler.codec.http.DefaultHttpResponse; import org.jboss.netty.handler.codec.http.HttpMessage; import org.jboss.netty.handler.codec.http.HttpMessageDecoder; +import org.jboss.netty.handler.codec.http.HttpResponse; /** + * Decodes {@link ChannelBuffer}s into {@link HttpResponse}s whose status is + * {@link RtspResponseStatus} and protocol version is {@link RtspVersion}. + *

+ * Please refer to {@link HttpMessageDecoder} for the detailed information on + * how this decoder works and what parameters are available. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Amit Bhayani (amit.bhayani@gmail.com) @@ -28,10 +35,18 @@ import org.jboss.netty.handler.codec.http.HttpMessageDecoder; */ public class RtspResponseDecoder extends HttpMessageDecoder { + /** + * Creates a new instance with the default + * {@code maxInitialLineLength (4096}}, {@code maxHeaderSize (4096)}, and + * {@code maxChunkSize (4096)}. + */ public RtspResponseDecoder() { super(); } + /** + * Creates a new instance with the specified parameters. + */ public RtspResponseDecoder(int maxInitialLineLength, int maxHeaderSize, int maxChunkSize) { super(maxInitialLineLength, maxHeaderSize, maxChunkSize); diff --git a/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspResponseStatus.java b/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspResponseStatus.java index 0e61f065a4..77e8ca7a67 100644 --- a/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspResponseStatus.java +++ b/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspResponseStatus.java @@ -18,6 +18,7 @@ package org.jboss.netty.handler.codec.rtsp; import org.jboss.netty.handler.codec.http.HttpResponseStatus; /** + * The status code and its description of a RTSP response. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Amit Bhayani (amit.bhayani@gmail.com) @@ -128,6 +129,14 @@ public class RtspResponseStatus extends HttpResponseStatus { 551, "Option not supported"); + /** + * Returns the {@link HttpResponseStatus} represented by the specified code. + * If the specified code is a standard RTSP or HTTP status code, a cached + * instance will be returned. Otherwise, a new instance will be returned. + * Please note that this method does not return {@link RtspResponseStatus} + * but returns {@link HttpResponseStatus} because RTSP re-uses many HTTP + * response status codes. + */ public static HttpResponseStatus valueOf(int code) { switch (code) { case 250: return LOW_STORAGE_SPACE; @@ -151,6 +160,10 @@ public class RtspResponseStatus extends HttpResponseStatus { } } + /** + * Creates a new instance with the specified {@code code} and its + * {@code reasonPhrase}. + */ public RtspResponseStatus(int code, String reasonPhrase) { super(code, reasonPhrase); } diff --git a/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspVersion.java b/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspVersion.java index aef405db08..886bd0bd1b 100644 --- a/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspVersion.java +++ b/src/main/java/org/jboss/netty/handler/codec/rtsp/RtspVersion.java @@ -18,6 +18,7 @@ package org.jboss.netty.handler.codec.rtsp; import org.jboss.netty.handler.codec.http.HttpVersion; /** + * The version of RTSP. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Amit Bhayani (amit.bhayani@gmail.com) @@ -26,16 +27,17 @@ import org.jboss.netty.handler.codec.http.HttpVersion; */ public class RtspVersion extends HttpVersion { + /** + * RTSP/1.0 + */ public static final RtspVersion RTSP_1_0 = new RtspVersion("RTSP", 1, 0); - public RtspVersion(String text) { - super(text); - } - - public RtspVersion(String protocolName, int majorVersion, int minorVersion) { - super(protocolName, majorVersion, minorVersion); - } - + /** + * Returns an existing or new {@link RtspVersion} instance which matches to + * the specified protocol version string. If the specified {@code text} is + * equal to {@code "RTSP/1.0"}, {@link #RTSP_1_0} will be returned. + * Otherwise, a new {@link RtspVersion} instance will be returned. + */ public static RtspVersion valueOf(String text) { if (text == null) { throw new NullPointerException("text"); @@ -48,4 +50,19 @@ public class RtspVersion extends HttpVersion { return new RtspVersion(text); } + + /** + * Creates a new RTSP version with the specified version string. + */ + public RtspVersion(String text) { + super(text); + } + + /** + * Creates a new HTTP version with the specified protocol name and version + * numbers. + */ + public RtspVersion(String protocolName, int majorVersion, int minorVersion) { + super(protocolName, majorVersion, minorVersion); + } } diff --git a/src/main/java/org/jboss/netty/handler/codec/rtsp/package-info.java b/src/main/java/org/jboss/netty/handler/codec/rtsp/package-info.java new file mode 100644 index 0000000000..f00a025f82 --- /dev/null +++ b/src/main/java/org/jboss/netty/handler/codec/rtsp/package-info.java @@ -0,0 +1,21 @@ +/* + * Copyright 2009 Red Hat, Inc. + * + * Red Hat licenses this file to you under the Apache License, version 2.0 + * (the "License"); you may not use this file except in compliance with the + * License. You may obtain a copy of the License at: + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations + * under the License. + */ + +/** + * An RTSP + * extension based on the HTTP codec. + */ +package org.jboss.netty.handler.codec.rtsp;