You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jira@kafka.apache.org by GitBox <gi...@apache.org> on 2022/12/01 17:04:59 UTC

[GitHub] [kafka] gharris1727 opened a new pull request, #12936: KAFKA-13881: Add Streams package infos

gharris1727 opened a new pull request, #12936:
URL: https://github.com/apache/kafka/pull/12936

   Signed-off-by: Greg Harris <gr...@aiven.io>
   
   Split off from #12895 to target only Streams packages.
   
   There are currently no descriptions of packages in the javadocs, which can be intimidating to new users that look at the documentation and see a wall of raw package names. An example of this can be seen here: https://kafka.apache.org/31/javadoc/
   
   This change adds the following package descriptions based on a best-effort reading of the existing javadocs. Please feel free to correct any factual errors in the proposed descriptions, I am not asserting that these descriptions are currently accurate. Currently the only package with new descriptions is clients, and I will be adding commits to this PR to address missing descriptions in the other packages (connect, core, streams)
   
   For clarity of review, I'll summarize the new descriptions in a table. This summary may become stale by accident, so please be sure to view the diff itself or build the changes locally with `./gradlew javadoc`.
   
   Package | Description
   --- | ---
   org.apache.kafka.streams|Provides the Kafka Streams library for building streaming data applications.
   org.apache.kafka.streams.errors|Provides common exception classes for Streams applications.
   org.apache.kafka.streams.kstream|Provides high-level abstractions of streaming data and computation over that streaming data.
   org.apache.kafka.streams.processor|Provides low-level abstractions of streaming data and computation over that streaming data.
   org.apache.kafka.streams.processor.api|Provides low-level abstractions of streaming data and computation over that streaming data.
   org.apache.kafka.streams.query|Provides API for extracting data from a Streams application.
   org.apache.kafka.streams.state|Provides interfaces for managing the intermediate state of a stateful streams application.
   org.apache.kafka.streams.test|Provides classes for testing Streams applications with mocked inputs.
   
   ### Committer Checklist (excluded from commit message)
   - [ ] Verify design and implementation 
   - [ ] Verify test coverage and CI build status
   - [ ] Verify documentation (including upgrade notes)
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] mjsax commented on a diff in pull request #12936: KAFKA-13881: Add Streams package infos

Posted by GitBox <gi...@apache.org>.
mjsax commented on code in PR #12936:
URL: https://github.com/apache/kafka/pull/12936#discussion_r1057837718


##########
streams/src/main/java/org/apache/kafka/streams/processor/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF 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.
+ */
+/**
+ * Provides low-level abstractions of streaming data and computation over that streaming data.

Review Comment:
   What about this:
   ```
   Provides a low-level programming model (Processor API, aka, PAPI) to express a (stateful) data flow computation over input topics. Use {@link org.apache.kafka.streams.Topology} as entry for your program.
   
   Note: some class are deprecated in favor of class provided via package{@link org.apache.kafka.streams.processor.api}
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] mjsax commented on pull request #12936: KAFKA-13881: Add Streams package infos

Posted by GitBox <gi...@apache.org>.
mjsax commented on PR #12936:
URL: https://github.com/apache/kafka/pull/12936#issuecomment-1366261412

   Thanks for the PR, @gharris1727.
   
   Merged to `trunk` and cherry-picked to `3.4` branch.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] mjsax commented on a diff in pull request #12936: KAFKA-13881: Add Streams package infos

Posted by GitBox <gi...@apache.org>.
mjsax commented on code in PR #12936:
URL: https://github.com/apache/kafka/pull/12936#discussion_r1057835843


##########
streams/src/main/java/org/apache/kafka/streams/kstream/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF 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.
+ */
+/**
+ * Provides high-level abstractions of streaming data and computation over that streaming data.

Review Comment:
   What about this:
   ```
   Provides a high-level programming model (DSL) to express a (stateful) data flow computation over input {@link KStream streams} and {@link KTable tables}. Use {@link StreamsBuilder} as entry for your program.
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] mjsax commented on a diff in pull request #12936: KAFKA-13881: Add Streams package infos

Posted by GitBox <gi...@apache.org>.
mjsax commented on code in PR #12936:
URL: https://github.com/apache/kafka/pull/12936#discussion_r1057835843


##########
streams/src/main/java/org/apache/kafka/streams/kstream/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF 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.
+ */
+/**
+ * Provides high-level abstractions of streaming data and computation over that streaming data.

Review Comment:
   What about this:
   ```
   Provides a high-level programming model (DSL) to express a (stateful) data flow computation over input {@link KStream streams} and {@link KTable tables}. Use {@link org.apache.kafka.streams.StreamsBuilder} as entry for your program.
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] mimaison commented on pull request #12936: KAFKA-13881: Add Streams package infos

Posted by GitBox <gi...@apache.org>.
mimaison commented on PR #12936:
URL: https://github.com/apache/kafka/pull/12936#issuecomment-1361845545

   @mjsax @ableegoldman Can you take a look? Thanks


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] mjsax commented on a diff in pull request #12936: KAFKA-13881: Add Streams package infos

Posted by GitBox <gi...@apache.org>.
mjsax commented on code in PR #12936:
URL: https://github.com/apache/kafka/pull/12936#discussion_r1057837718


##########
streams/src/main/java/org/apache/kafka/streams/processor/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF 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.
+ */
+/**
+ * Provides low-level abstractions of streaming data and computation over that streaming data.

Review Comment:
   Same as for `processer.api`



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] mjsax commented on a diff in pull request #12936: KAFKA-13881: Add Streams package infos

Posted by GitBox <gi...@apache.org>.
mjsax commented on code in PR #12936:
URL: https://github.com/apache/kafka/pull/12936#discussion_r1057837322


##########
streams/src/main/java/org/apache/kafka/streams/processor/api/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF 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.
+ */
+/**
+ * Provides low-level abstractions of streaming data and computation over that streaming data.

Review Comment:
   What about this:
   ```
   Provides a low-level programming model (Processor API, aka, PAPI) to express a (stateful) data flow computation over input topics. Use {@link org.apache.kafka.streams.Topology} as entry for your program.
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] mjsax commented on a diff in pull request #12936: KAFKA-13881: Add Streams package infos

Posted by GitBox <gi...@apache.org>.
mjsax commented on code in PR #12936:
URL: https://github.com/apache/kafka/pull/12936#discussion_r1057839203


##########
streams/src/main/java/org/apache/kafka/streams/query/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF 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.
+ */
+/**
+ * Provides API for extracting data from a Streams application.

Review Comment:
   What about this:
   ```
   Provides a query API (aka Interactive Queries) over state stores, for extracting data from a stateful Kafka Streams application.
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] mjsax commented on a diff in pull request #12936: KAFKA-13881: Add Streams package infos

Posted by GitBox <gi...@apache.org>.
mjsax commented on code in PR #12936:
URL: https://github.com/apache/kafka/pull/12936#discussion_r1057839578


##########
streams/test-utils/src/main/java/org/apache/kafka/streams/test/package-info.java:
##########
@@ -0,0 +1,20 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF 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.
+ */
+/**
+ * Provides classes for testing Streams applications with mocked inputs.

Review Comment:
   ```suggestion
    * Provides classes for testing Kafka Streams applications with mocked inputs.
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [kafka] mjsax merged pull request #12936: KAFKA-13881: Add Streams package infos

Posted by GitBox <gi...@apache.org>.
mjsax merged PR #12936:
URL: https://github.com/apache/kafka/pull/12936


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org