jericho 2002/07/25 04:00:52
Modified: src/util/org/apache/util URI.java
Log:
- Fix some document contents and javadoc....
Revision Changes Path
1.10 +79 -61 jakarta-slide/src/util/org/apache/util/URI.java
Index: URI.java
===================================================================
RCS file: /home/cvs/jakarta-slide/src/util/org/apache/util/URI.java,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- URI.java 7 Jul 2002 02:22:18 -0000 1.9
+++ URI.java 25 Jul 2002 11:00:52 -0000 1.10
@@ -98,13 +98,12 @@
* <p>
*
* URI Syntactic Components
- * - In general, written as follows:
* <p><blockquote><pre>
- * Absolute URI = <scheme>:<scheme-specific-part>
- * Generic URI = <scheme>://<authority><path>?<query>
- * </pre></blockquote><p>
+ * - In general, written as follows:
+ * Absolute URI = <scheme>:<scheme-specific-part>
+ * Generic URI = <scheme>://<authority><path>?<query>
+ *
* - Syntax
- * <p><blockquote><pre>
* absoluteURI = scheme ":" ( hier_part | opaque_part )
* hier_part = ( net_path | abs_path ) [ "?" query ]
* net_path = "//" authority [ abs_path ]
@@ -112,6 +111,7 @@
* </pre></blockquote><p>
*
* The following examples illustrate URI that are in common use.
+ * <pre>
* ftp://ftp.is.co.za/rfc/rfc1808.txt
* -- ftp scheme for File Transfer Protocol services
* gopher://spinaltap.micro.umn.edu/00/Weather/California/Los%20Angeles
@@ -124,9 +124,24 @@
* -- news scheme for USENET news groups and articles
* telnet://melvyl.ucop.edu/
* -- telnet scheme for interactive services via the TELNET Protocol
- * <p>
+ * </pre>
* Please, notice that there are many modifications from URL(RFC 1738) and
* relative URL(RFC 1808).
+ * <p>
+ * <b>The recommendation to use the URI class</b>
+ * <p><pre>
+ * Communication function level
+ * - URI(<code>char</code>[]) // constructor
+ * - <code>char</code>[] getRawXxx() // method
+ * <p>
+ * Document and data processing function level
+ * - URI(<code>String</code>) // constructor
+ * - <code>String</code> getXXX() // method
+ * <p>
+ * Both Level
+ * - <code>String</code> getEscapedXxx() // method
+ * - <code>String</code> toString() // method
+ * </pre><p>
*
* @author <a href="mailto:[EMAIL PROTECTED]";>Sung-Gu</a>
* @version $Revision$ $Date: 2002/03/14 15:14:01
@@ -1358,10 +1373,10 @@
* table that includes the local character set code and the corresponding
* UCS code.
* The next step is to convert the UCS character code to the UTF-8 encoding.
- *
+ * <p>
* Mapping between vendor codepages can be done in a very similar manner
* as described above.
- *
+ * <p>
* The only time escape encodings can allowedly be made is when a URI is
* being created from its component parts. The escape and validate methods
* are internally performed within this method.
@@ -1371,7 +1386,7 @@
* @return URI character sequence
* @exception UnsupportedEncodingException unsupported character encoding
* @exception URIException null component
- * @see escape
+ * @see #escape
*/
protected char[] encode(String original, BitSet allowed)
throws UnsupportedEncodingException, URIException {
@@ -1394,13 +1409,13 @@
*
* A URI must be separated into its components before the escaped
* characters within those components can be allowedly decoded.
- *
+ * <p>
* Notice that there is a chance that URI characters that are non UTF-8
* may be parsed as valid UTF-8. A recent non-scientific analysis found
* that EUC encoded Japanese words had a 2.7% false reading; SJIS had a
* 0.0005% false reading; other encoding such as ASCII or KOI-8 have a 0%
* false reading.
- *
+ * <p>
* The unescape method is internally performed within this method.
*
* @param octet the octet sequence
@@ -1408,7 +1423,7 @@
* @exception UnsupportedEncodingException unsupported character encoding
* @exception URIException incomplete trailing escape pattern
* @throws NullPointerException null argument
- * @see unescape
+ * @see #unescape
*/
protected String decode(char[] uri)
throws UnsupportedEncodingException, URIException {
@@ -1426,7 +1441,7 @@
*
* An escaped octet is encoded as a character triplet, consisting of the
* percent character "%" followed by the two hexadecimal digits
- * representing the octet code. For exsurrogateample, "%20" is the escaped
+ * representing the octet code. For example, "%20" is the escaped
* encoding for the US-ASCII space character.
*
* @param octet the octet sequence to be escaped
@@ -1465,6 +1480,7 @@
buf.append(hexadecimal);
}
}
+
return buf.toString().toCharArray();
}
@@ -1554,7 +1570,7 @@
* Validate the URI characters within a specific component.
* The component must be performed after escape encoding. Or it doesn't
* include escaped characters.
- *
+ * <p>
* It's not that much strict, generous. The strict validation might be
* performed before being called this method.
*
@@ -1956,7 +1972,7 @@
/**
* Once it's parsed successfully, set this URI.
*
- * @see getRawURI
+ * @see #getRawURI
*/
protected void setUriReference() {
// set _uri
@@ -2050,7 +2066,7 @@
* It's the same function as the has_authority() method.
*
* @return true iif the relativeURI or heir_part is net_path
- * @see has_authority
+ * @see #hasAuthority
*/
public boolean isNetPath() {
return _is_net_path || (_authority != null);
@@ -2082,7 +2098,7 @@
* It's the same function as the is_net_path() method.
*
* @return true iif this URI has authority
- * @see is_net_path
+ * @see #isNetPath
*/
public boolean hasAuthority() {
return (_authority != null) || _is_net_path;
@@ -2173,7 +2189,7 @@
/**
* Set the default charset of the protocol.
- *
+ * <p>
* The character set used to store files SHALL remain a local decision and
* MAY depend on the capability of local operating systems. Prior to the
* exchange of URIs they SHOULD be converted into a ISO/IEC 10646 format
@@ -2181,7 +2197,7 @@
* of URIs, will still allow backward compatibility with older systems
* because the code set positions for ASCII characters are identical to the
* one byte sequence in UTF-8.
- *
+ * <p>
* An individual URI scheme may require a single charset, define a default
* charset, or provide a way to indicate the charset used.
*
@@ -2194,10 +2210,10 @@
/**
* Get the default charset of the protocol.
- *
+ * <p>
* An individual URI scheme may require a single charset, define a default
* charset, or provide a way to indicate the charset used.
- *
+ * <p>
* To work globally either requires support of a number of character sets
* and to be able to convert between them, or the use of a single preferred
* character set.
@@ -2213,9 +2229,9 @@
/**
* Set the default charset of the document.
- *
+ * <p>
* Notice that it will be possible to contain mixed characters (e.g.
- * ftp://ChineseDirectoryName/KoreanFileName). To handle the Bi-directional
+ * ftp://host/KoreanNamespace/ChineseResource). To handle the Bi-directional
* display of these character sets, the protocol charset could be simply
* used again. Because it's not yet implemented that the insertion of BIDI
* control characters at different points during composition is extracted.
@@ -2305,7 +2321,7 @@
* @return the authority
* @exception UnsupportedEncodingException
* @exception URIException
- * @see decode
+ * @see #decode
*/
public String getAuthority()
throws UnsupportedEncodingException, URIException {
@@ -2319,7 +2335,7 @@
* Get the raw-escaped userinfo.
*
* @return the raw-escaped userinfo
- * @see getAuthority
+ * @see #getAuthority
*/
public char[] getRawUserinfo() {
return _userinfo;
@@ -2330,7 +2346,7 @@
* Get the escaped userinfo.
*
* @return the escaped userinfo
- * @see getAuthority
+ * @see #getAuthority
*/
public String getEscapedUserinfo() {
return new String(_userinfo);
@@ -2343,8 +2359,8 @@
* @return the userinfo
* @exception UnsupportedEncodingException
* @exception URIException
- * @see decode
- * @see getAuthority
+ * @see #decode
+ * @see #getAuthority
*/
public String getUserinfo()
throws UnsupportedEncodingException, URIException {
@@ -2361,7 +2377,7 @@
* </pre></blockquote><p>
*
* @return the host
- * @see getAuthority
+ * @see #getAuthority
*/
public char[] getRawHost() {
return _host;
@@ -2377,8 +2393,8 @@
* @return the host
* @exception UnsupportedEncodingException
* @exception URIException
- * @see decode
- * @see getAuthority
+ * @see #decode
+ * @see #getAuthority
*/
public String getHost()
throws UnsupportedEncodingException, URIException {
@@ -2409,7 +2425,7 @@
* @param path the path string
* @exception UnsupportedEncodingException
* @exception URIException set incorrectly or fragment only
- * @see encode
+ * @see #encode
*/
protected void setPath(String path)
throws UnsupportedEncodingException, URIException {
@@ -2529,7 +2545,7 @@
* @return the current hierarchy level
* @exception UnsupportedEncodingException
* @exception URIException
- * @see decode
+ * @see #decode
*/
public String getCurrentHierPath()
throws UnsupportedEncodingException, URIException {
@@ -2572,7 +2588,7 @@
* @return the above hierarchy level
* @exception UnsupportedEncodingException
* @exception URIException
- * @see decode
+ * @see #decode
*/
public String getAboveHierPath()
throws UnsupportedEncodingException, URIException {
@@ -2617,7 +2633,7 @@
* @return the path string
* @exception UnsupportedEncodingException
* @exception URIException
- * @see decode
+ * @see #decode
*/
public String getPath()
throws UnsupportedEncodingException, URIException {
@@ -2667,7 +2683,7 @@
* @return the basename string
* @exception UnsupportedEncodingException unsupported character encoding
* @exception URIException incomplete trailing escape pattern
- * @see decode
+ * @see #decode
*/
public String getName()
throws UnsupportedEncodingException, URIException {
@@ -2724,7 +2740,7 @@
* @return the path and query string.
* @exception UnsupportedEncodingException unsupported character encoding
* @exception URIException incomplete trailing escape pattern
- * @see decode
+ * @see #decode
*/
public String getPathQuery()
throws UnsupportedEncodingException, URIException {
@@ -2741,7 +2757,7 @@
* @exception UnsupportedEncodingException unsupported character encoding
* @exception URIException incomplete trailing escape pattern
* @throws NullPointerException null query
- * @see encode
+ * @see #encode
*/
public void setQuery(String query)
throws UnsupportedEncodingException, URIException {
@@ -2779,7 +2795,7 @@
* @exception UnsupportedEncodingException unsupported character encoding
* @exception URIException incomplete trailing escape pattern
* @throws NullPointerException undefined query
- * @see decode
+ * @see #decode
*/
public String getQuery()
throws UnsupportedEncodingException, URIException {
@@ -2791,7 +2807,7 @@
/**
* Set the fragment.
- *
+ * <p>
* An empty URI reference represents the base URI of the current document
* and should be replaced by that URI when transformed into a request.
*
@@ -2810,13 +2826,13 @@
/**
* Get the raw-escaped fragment.
- *
+ * <p>
* The optional fragment identifier is not part of a URI, but is often used
* in conjunction with a URI.
- *
+ * <p>
* The format and interpretation of fragment identifiers is dependent on
* the media type [RFC2046] of the retrieval result.
- *
+ * <p>
* A fragment identifier is only meaningful when a URI reference is
* intended for retrieval and the result of that retrieval is a document
* for which the identified fragment is consistently defined.
@@ -2846,7 +2862,7 @@
* @exception UnsupportedEncodingException unsupported character encoding
* @exception URIException incomplete trailing escape pattern
* @throws NullPointerException undefined fragment
- * @see decode
+ * @see #decode
*/
public String getFragment()
throws UnsupportedEncodingException, URIException {
@@ -3059,12 +3075,14 @@
// ------------------------------------------------------------------ Clone
/**
- * Create and return a copy of this object.
- *
+ * Create and return a copy of this object, the URI-reference containing
+ * the userinfo component. Notice that the whole URI-reference including
+ * the userinfo component counld not be gotten as a <code>String</code>.
+ * <p>
* To copy the identical <code>URI</code> object including the userinfo
* component, it should be used.
*
- * @return a clone of this instance, null if it's failed to copy
+ * @return a clone of this instance
*/
public synchronized Object clone() {
@@ -3101,13 +3119,13 @@
/**
* It can be gotten the URI character sequence. It's raw-escaped.
* For the purpose of the protocol to be transported, it will be useful.
- *
+ * <p>
* It is clearly unwise to use a URL that contains a password which is
* intended to be secret. In particular, the use of a password within
* the 'userinfo' component of a URL is strongly disrecommended except
* in those rare cases where the 'password' parameter is intended to be
* public.
- *
+ * <p>
* When you want to get each part of the userinfo, you need to use the
* specific methods in the specific URL. It depends on the specific URL.
*
@@ -3135,7 +3153,7 @@
* @return the URI string
* @exception UnsupportedEncodingException unsupported character encoding
* @exception URIException incomplete trailing escape pattern
- * @see decode
+ * @see #decode
*/
public String getURI()
throws UnsupportedEncodingException, URIException {
@@ -3146,20 +3164,20 @@
/**
* Get the escaped URI string.
- *
+ * <p>
* On the document, the URI-reference form is only used without the userinfo
* component like http://jakarta.apache.org/slide by the security reason.
- * But the user can specify and type the URI-reference form with the
- * userinfo component in the class.
- *
- * In other words, this URI and any its subclasses must not be exported the
+ * But the URI-reference form with the userinfo component could be parsed.
+ * <p>
+ * In other words, this URI and any its subclasses must not expose the
* URI-reference expression with the userinfo component like
- * http://user:password@hostport/restricted_zone.
+ * http://user:password@hostport/restricted_zone.<br>
* It means that the API client programmer should extract each user and
* password to access manually. Probably it will be supported in the each
* subclass, however, not a whole URI-reference expression.
*
- * @return the escaped URI string
+ * @return the URI string
+ * @see #clone()
*/
public String toString() {
return getEscapedURI();
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
