You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by ro...@apache.org on 2006/08/24 21:27:20 UTC
svn commit: r434476 - in
/jakarta/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http:
HttpConnection.java impl/AbstractHttpConnection.java
Author: rolandw
Date: Thu Aug 24 12:27:19 2006
New Revision: 434476
URL: http://svn.apache.org/viewvc?rev=434476&view=rev
Log:
JavaDoc and minor access fixes
Modified:
jakarta/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpConnection.java
jakarta/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/AbstractHttpConnection.java
Modified: jakarta/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpConnection.java
URL: http://svn.apache.org/viewvc/jakarta/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpConnection.java?rev=434476&r1=434475&r2=434476&view=diff
==============================================================================
--- jakarta/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpConnection.java (original)
+++ jakarta/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/HttpConnection.java Thu Aug 24 12:27:19 2006
@@ -43,38 +43,43 @@
public interface HttpConnection {
/**
- * This method will gracefully close the connection. It will attempt to
- * flush the transmitter's internal buffer prior to closing the underlying
- * socket. This method MAY NOT be called from a different thread to force
- * shutdown the connection. Use #shutdown() instead.
- *
- * @see #shutdown()
+ * Closes this connection gracefully.
+ * This method will attempt to flush the transmitter's
+ * internal buffer prior to closing the underlying socket.
+ * This method MUST NOT be called from a different thread to force
+ * shutdown of the connection. Use {@link #shutdown shutdown} instead.
*/
- void close() throws IOException;
+ public void close() throws IOException;
/**
* Checks if this connection is open.
* @return true if it is open, false if it is closed.
*/
- boolean isOpen();
+ public boolean isOpen();
/**
- * Network connections may get closed during some time of inactivity for several reasons.
- * The next time a read is attempted on such a connection it will throw an IOException.
- * This method tries to alleviate this inconvenience by trying to find out if a connection is still
- * usable. Implementations may do that by attempting a read with a very small timeout. Thus this
- * method may block for a small indefinite time before returning a result.
+ * Checks whether this connection has gone down.
+ * Network connections may get closed during some time of inactivity
+ * for several reasons. The next time a read is attempted on such a
+ * connection it will throw an IOException.
+ * This method tries to alleviate this inconvenience by trying to
+ * find out if a connection is still usable. Implementations may do
+ * that by attempting a read with a very small timeout. Thus this
+ * method may block for a small amount of time before returning a result.
+ * It is therefore an <i>expensive</i> operation.
*
- * @return true if attempts to use this connection are likely to succeed, false if they are likely
- * to fail and this connection should be closed and discarded.
+ * @return <code>true</code> if attempts to use this connection are
+ * likely to succeed, or <code>false</code> if they are likely
+ * to fail and this connection should be closed
*/
- boolean isStale();
+ public boolean isStale();
/**
- * This method will force close the connection. This is the only method,
- * which may be called from a different thread to terminate the connection.
- * This method will not attempt to flush the transmitter's internal buffer
- * prior to closing the underlying socket.
+ * Force-closes this connection.
+ * This is the only method of a connection which may be called
+ * from a different thread to terminate the connection.
+ * This method will not attempt to flush the transmitter's
+ * internal buffer prior to closing the underlying socket.
*/
- void shutdown() throws IOException;
+ public void shutdown() throws IOException;
}
Modified: jakarta/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/AbstractHttpConnection.java
URL: http://svn.apache.org/viewvc/jakarta/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/AbstractHttpConnection.java?rev=434476&r1=434475&r2=434476&view=diff
==============================================================================
--- jakarta/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/AbstractHttpConnection.java (original)
+++ jakarta/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/impl/AbstractHttpConnection.java Thu Aug 24 12:27:19 2006
@@ -51,7 +51,7 @@
*
* @since 4.0
*/
-abstract class AbstractHttpConnection implements HttpConnection {
+public abstract class AbstractHttpConnection implements HttpConnection {
/*
* I/O operations may not be performed if this flag is set to false
Re: svn commit: r434476
Posted by Roland Weber <ht...@dubioso.net>.
Hi Ryan,
> To whomever it may concern,
>
> If you use an cool little IDE like Eclipse, they have excellent code
> formatting in 3.2 version making the nuances of code formatting
> completely trivial, you can configure pretty much any aspect of
> formatting code.
I have stated my view on IDEs on other occasions. I think they are
way less cool than you think they are. My Emacs is perfectly capable
of indenting code, and that's all I want it to do. What I heard about
automatic formatting of Eclipse based tools is that they have problems
with fully qualified classnames at the line end:
... x instanceof fully.
qualified.
series.
of.
packages.
before.
ClassName)...
> Ever since this invention, i no longer spend even more than 2 seconds on
> code formatting issues. I just right click> src > format and it does
> the whole code tree. I usually do a src format once a month to clean
> out the cobwebs.
If that's good enough for you. I expect code to be readable whenever
I look at it, whether it's during development or when looking up
something because of a user question. I've taught Emacs my preferred
indenting style years ago. I had to adjust indentation for HttpClient,
since we're using a different style here. But I sure won't swap my
editor which has served my well since 15 years for an IDE.
The main reason why I loathe IDEs - besides them not integrating Emacs -
is that I have observed too much sloppiness about those things that
the IDE makes seemingly easy. Indentation is just one example, build
process another. Studying of documentation vs. automatic expansion of
method names; generating bad code because it's so easy to refactor
later (which hardly anyone actually does)... don't get me started! ;-)
You know something's wrong with your development process when code
is exchanged between developers by copying full projects using a
USB stick instead of checking files in and out of a source code
repository. Oh how they were jealous about my 512 MB stick, while
they had 64 MB sticks on which only a single project would fit.
cheers,
Roland
---------------------------------------------------------------------
To unsubscribe, e-mail: httpclient-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpclient-dev-help@jakarta.apache.org
Re: svn commit: r434476
Posted by Ryan Smith <rs...@livedatagroup.com>.
To whomever it may concern,
If you use an cool little IDE like Eclipse, they have excellent code
formatting in 3.2 version making the nuances of code formatting
completely trivial, you can configure pretty much any aspect of
formatting code.
Ever since this invention, i no longer spend even more than 2 seconds on
code formatting issues. I just right click> src > format and it does
the whole code tree. I usually do a src format once a month to clean
out the cobwebs.
Enjoy,
-Ryan
Roland Weber wrote:
> Hi Julius,
>
>> +1 to Oleg, because it shows excellent knowledge of Java language, and
>> is certainly a little more readable, especially with those long method
>> names that go beyond 80 columns.
>>
>> +1 to Roland, though, because when I implement the interface, I have
>> weird habits and I always just "copy & paste" from the interface, and
>> then I get annoyed that I have to remember to add the "public" in my
>> concrete class.
>
> To make the confusion complete: I am adding the "public" although I'm
> using an editor in 80 column mode. The trick is to add line breaks in
> places where they do not irritate the syntax highlighting :-)
>
> public final static
> Object createObject(String arg1,
> Map arg2)
> throws Exception
>
> But even so, when long class names of the return value _and_ an argument
> team up with a long method name, there's nothing I can do anymore...
>
> cheers,
> Roland
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: httpclient-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: httpclient-dev-help@jakarta.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: httpclient-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpclient-dev-help@jakarta.apache.org
Re: svn commit: r434476
Posted by Roland Weber <ht...@dubioso.net>.
Hi Julius,
> +1 to Oleg, because it shows excellent knowledge of Java language, and
> is certainly a little more readable, especially with those long method
> names that go beyond 80 columns.
>
> +1 to Roland, though, because when I implement the interface, I have
> weird habits and I always just "copy & paste" from the interface, and
> then I get annoyed that I have to remember to add the "public" in my
> concrete class.
To make the confusion complete: I am adding the "public" although I'm
using an editor in 80 column mode. The trick is to add line breaks in
places where they do not irritate the syntax highlighting :-)
public final static
Object createObject(String arg1,
Map arg2)
throws Exception
But even so, when long class names of the return value _and_ an argument
team up with a long method name, there's nothing I can do anymore...
cheers,
Roland
---------------------------------------------------------------------
To unsubscribe, e-mail: httpclient-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpclient-dev-help@jakarta.apache.org
Re: svn commit: r434476
Posted by Julius Davies <ju...@cucbc.com>.
+1 to Oleg, because it shows excellent knowledge of Java language, and
is certainly a little more readable, especially with those long method
names that go beyond 80 columns.
+1 to Roland, though, because when I implement the interface, I have
weird habits and I always just "copy & paste" from the interface, and
then I get annoyed that I have to remember to add the "public" in my
concrete class.
I guess I'm not really helping much here. :-p
On Thu, 2006-24-08 at 21:53 +0200, Oleg Kalnichevski wrote:
> On Thu, 2006-08-24 at 19:27 +0000, rolandw@apache.org wrote:
> > - void close() throws IOException;
> > + public void close() throws IOException;
>
> Roland,
>
> I have a pretty bizarre and verbose coding style and therefore do not
> try to impose a consistent coding guidelines onto my fellow committers.
> In this particular case, though, I think declaring an interface method
> public does not bring anything. All methods in an interface are public
> and public only. Is there a particular reason you want methods in this
> interface explicitly declared public? I find interfaces without public
> declarations a _little_ more readable than with.
>
> BTW, many thanks for cleaning up Javadocs. I, for one, owe you a lot for
> doing it.
>
> Evil Comrade Oleg
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: httpclient-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: httpclient-dev-help@jakarta.apache.org
>
--
Julius Davies
Senior Application Developer, Technology Services
Credit Union Central of British Columbia
http://www.cucbc.com/
Tel: 604-730-6385
Cel: 604-868-7571
Fax: 604-737-5910
1441 Creekside Drive
Vancouver, BC
Canada
V6J 4S7
---------------------------------------------------------------------
To unsubscribe, e-mail: httpclient-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpclient-dev-help@jakarta.apache.org
Re: svn commit: r434476
Posted by Roland Weber <ht...@dubioso.net>.
Hi Oleg,
> There are no lead developers here. This is no "I have a bigger title, I
> deserve a bigger bonus" corporate shit. Your vote means as much as mine,
> so does your opinion. Please leave public declarations be if you find
> them useful.
It's not corporate shit, but still: the more you contribute, the higher
is your status in an open source community. It's a fact that you have
put by far the most work into the HttpComponents code base, and that you
are likely to continue to do so for the forseeable future. So there is
no point in inconveniencing you often instead of inconveniencing me
rarely.
I'll leave the public declarations in the interface I already changed,
but I won't add any more in the future.
cheers,
Roland
---------------------------------------------------------------------
To unsubscribe, e-mail: httpclient-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpclient-dev-help@jakarta.apache.org
Re: svn commit: r434476
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Thu, 2006-08-24 at 22:29 +0200, Roland Weber wrote:
> Hi Oleg,
>
> > In this particular case, though, I think declaring an interface method
> > public does not bring anything. All methods in an interface are public
> > and public only. Is there a particular reason you want methods in this
> > interface explicitly declared public? I find interfaces without public
> > declarations a _little_ more readable than with.
>
> I don't like to have two different ways of declaring method signatures,
> and having to decide which one is appropriate. In this particular case,
> I copied and pasted the signature from the interface into the class in
> which I wanted to implement it, and it was wrong because of the missing
> "public" declaration which I had to substitute. It is quite common for
> me to paste signatures from interfaces into implementation classes. But
> since you are the lead developer
Roland,
There are no lead developers here. This is no "I have a bigger title, I
deserve a bigger bonus" corporate shit. Your vote means as much as mine,
so does your opinion. Please leave public declarations be if you find
them useful.
Cheers
Oleg
> , I'll refrain from adding "public" to
> (non-async) interfaces in the future. The new connection interfaces I
> am currently prototyping will have the public declaration, though.
>
> > BTW, many thanks for cleaning up Javadocs. I, for one, owe you a lot for
> > doing it.
>
> You're welcome.
>
> cheers,
> Roland
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: httpclient-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: httpclient-dev-help@jakarta.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: httpclient-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpclient-dev-help@jakarta.apache.org
Re: svn commit: r434476
Posted by Roland Weber <ht...@dubioso.net>.
Hi Oleg,
> In this particular case, though, I think declaring an interface method
> public does not bring anything. All methods in an interface are public
> and public only. Is there a particular reason you want methods in this
> interface explicitly declared public? I find interfaces without public
> declarations a _little_ more readable than with.
I don't like to have two different ways of declaring method signatures,
and having to decide which one is appropriate. In this particular case,
I copied and pasted the signature from the interface into the class in
which I wanted to implement it, and it was wrong because of the missing
"public" declaration which I had to substitute. It is quite common for
me to paste signatures from interfaces into implementation classes. But
since you are the lead developer, I'll refrain from adding "public" to
(non-async) interfaces in the future. The new connection interfaces I
am currently prototyping will have the public declaration, though.
> BTW, many thanks for cleaning up Javadocs. I, for one, owe you a lot for
> doing it.
You're welcome.
cheers,
Roland
---------------------------------------------------------------------
To unsubscribe, e-mail: httpclient-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpclient-dev-help@jakarta.apache.org
Re: svn commit: r434476
Posted by Ortwin Glück <od...@odi.ch>.
I dislike unnecessary public modifiers in interfaces too.
my 0.05 CHF
Odi
---------------------------------------------------------------------
To unsubscribe, e-mail: httpclient-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpclient-dev-help@jakarta.apache.org
Re: svn commit: r434476
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Thu, 2006-08-24 at 19:27 +0000, rolandw@apache.org wrote:
> - void close() throws IOException;
> + public void close() throws IOException;
Roland,
I have a pretty bizarre and verbose coding style and therefore do not
try to impose a consistent coding guidelines onto my fellow committers.
In this particular case, though, I think declaring an interface method
public does not bring anything. All methods in an interface are public
and public only. Is there a particular reason you want methods in this
interface explicitly declared public? I find interfaces without public
declarations a _little_ more readable than with.
BTW, many thanks for cleaning up Javadocs. I, for one, owe you a lot for
doing it.
Evil Comrade Oleg
---------------------------------------------------------------------
To unsubscribe, e-mail: httpclient-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpclient-dev-help@jakarta.apache.org