Sitelet https://web.archive.org/web/20200709105653/https://github.com/grpc/grpc-java/issues/6552
Skip to content

/ grpc-java

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify the Javadoc for CallStreamObserver #6552

Open
leventov opened this issue Dec 19, 2019 · 3 comments
Open

Clarify the Javadoc for CallStreamObserver #6552

leventov opened this issue Dec 19, 2019 · 3 comments
Labels
docs enhancement
Milestone
Next

Comments

@leventov
Copy link
Contributor

@leventov leventov commented Dec 19, 2019

The relevant part of the current Javadoc:

grpc-java/stub/src/main/java/io/grpc/stub/CallStreamObserver.java

Lines 25 to 35 in 6b04fc1

* <p>In any call there are logically two {@link StreamObserver} implementations:
* <ul>
* <li>'inbound' - which the GRPC runtime calls when it receives messages from the
* remote peer. This is implemented by the application.
* </li>
* <li>'outbound' - which the GRPC runtime provides to the application which it uses to
* send messages to the remote peer.
* </li>
* </ul>
*
* <p>Implementations of this class represent the 'outbound' message stream.

As far as I can tell, for any call, there are three implementations of StreamObserver involved:

  1. Implemented by the application, on the RPC client side ('inbound')
  2. Implemented by the framework, on the RPC client side ('outbound'), ClientCallStreamObserver
  3. Implemented by the framework, on the RPC server side ('outbound'), ServerCallStreamObserver

I think it would be nice to clarify that. I've spent significant time trying to understand where does ClientCallStreamObserver appear, being confused by the premise that there are only two implementations of StreamObserver.
@leventov leventov added the question label Dec 19, 2019
@ran-su
Copy link
Member

@ran-su ran-su commented Dec 19, 2019

Sometime, look at examples will help understand the APIs. I do agree with you some of our javadocs can be improved, and we are welcoming any contribution that helps our project. If you can send a pr to make the documentations better, we will be glad to review and merge it.
@leventov leventov mentioned this issue Dec 20, 2019
Merged
@creamsoup
Copy link
Contributor

@creamsoup creamsoup commented Jan 30, 2020

reopen this bug. Couple more clarifications are necessary as @leventov pointed out in the PR.
@leventov, do you want to fix the other two?
@creamsoup creamsoup reopened this Jan 30, 2020
@leventov
Copy link
Contributor Author

@leventov leventov commented Jan 31, 2020

No
@creamsoup creamsoup self-assigned this Jan 31, 2020
@creamsoup creamsoup added this to the 1.28 milestone Jan 31, 2020
@creamsoup creamsoup modified the milestones: 1.28, 1.29 Feb 27, 2020
@dapengzhang0 dapengzhang0 modified the milestones: 1.29, 1.30 Apr 7, 2020
@ejona86 ejona86 modified the milestones: 1.30, Next May 19, 2020
@creamsoup creamsoup removed their assignment Jul 8, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs enhancement
Projects
None yet
Milestone
Next
Linked pull requests

Successfully merging a pull request may close this issue.

Clarify CallStreamObserver's Javadoc
5 participants
@leventov @creamsoup @ran-su @ejona86 @dapengzhang0
You can’t perform that action at this time.