--- title: "Jam 01 - Exercise 3 - Understanding the Java API Documentation" tags: - 3 🧪 in testing - 4 🥳 done - jam01 - java - documentation created: 2025-01-20 updated: 2025-01-20 --- <!-- markdownlint-disable line-length single-h1 no-inline-html --> <!-- markdownlint-configure-file { "ul-indent": { "indent": 4 }, "link-fragments": {"ignore_case": true} } --> # Exercise 3 - Understanding the Java API Documentation {%hackmd dJZ5TulxSDKme-3fSY4Lbw %} ## Overview - Exercise 3 The Java API (Application Programming Interface) is the most essential reference for Java development. It documents all the standard libraries and classes available in Java. Learning to navigate and understand the API documentation is a crucial skill for any Java developer. ## Required Steps - Exploring the API 1. **Access the Java API** - Open a browser window - Search for "Java 21 API" or go directly to: <https://docs.oracle.com/en/java/javase/21/docs/api/index.html> - Bookmark this page - you'll use it frequently throughout your Java career! 2. **Understanding API Organization** - Java organizes its libraries into **modules** and **packages** - A **module** is a collection of related packages (added in Java 9) - A **package** is a collection of related classes and interfaces :::info 🔑 **Key Concept: java.lang** - The `java.lang` package is automatically imported in every Java program - It contains fundamental classes like `System` and `String` - You never need to explicitly import it! ::: 3. **Exploring the System Class Java API Documentation** Let's explore the `System` class we used in HelloWorld: 1. Click on the **java.base** module (on the Java API Documentation website) 2. Find and click on the **java.lang** package 3. Locate and click on the **System** class 4. Notice the page structure: - Top: Brief description of the class - Middle: Summary of fields, constructors, and methods - Bottom: Detailed documentation 4. **Understanding System.out** - Find the `out` field in the System class - Notice it's of type `PrintStream` - Click on `PrintStream` to explore its methods - Find the various `println()` methods - This explains why we can use `System.out.println()`! >[!Important] Questions for answers.txt > >Create answers.txt in your jam01 folder, copy your header from your jam00/answers.txt file, and answer these questions: > > (3.1) Locate the description for println(String x) in the PrintStream class. What does this do? Copy and paste the description of the method. What methods does println(String x) actually call? > > (3.2) Go back to the page for the System class. The object out is the "standard" output stream. What is the object that represents the "standard" input stream? And, what is its type? > > (3.3) Look up the getProperties() method in the System class. What would the Java statement look like to print the Operating system name to System.out? > > (3.4) What is method overloading? (You can search online for an answer, or use the answer above!). 🔑 **Using Online Resources** When looking for Java API information: - If you know the exact function name, use the Java API search - Otherwise, Google often works better and leads to sites like stackoverflow.com - StackOverflow is particularly valuable - consider becoming an active member - **However:** Never copy/paste code without understanding it - Remember there's a lot of poor quality code online - Always strive to understand what you find >[!Important] Questions for answers.txt > >Create answers.txt in your jam01 folder, copy your header from your jam00/answers.txt file, and answer these questions: > > (3.5) Read about the nanoTime method. Can nanoTime be used to report the current wall-clock time? > > (3.6) What is the package of the Scanner class? > > (3.7) Would you need to include an explicit import statement to use Scanner? Or is it automatically included for you? (HINT: Is Scanner in java.lang?) > > (3.8) Find the sin method in the Math class. Does it take degrees or radians as its parameter? **Important Warning About AI and Documentation.** So, did you try to use ChatGPT to get those answers? Let's consider the question about nanoTime being used to compute wall time. We entered the question into ChatGPT, and this was our response: ![BadGPT](https://hackmd.io/_uploads/H1xhd9gdJe.png) Sounds convincing, right? Here's the *correct* answer from the actual Java 21 API: ![Good API](https://hackmd.io/_uploads/BkQT_9xO1x.png) :::danger 🚨 **CONSIDER YOURSELF WARNED!** Be careful with ChatGPT! Use your own brain to criticize the output! Never take its responses as ground truth. ::: 🚧 **Citation Requirements** When using any online resource (including ChatGPT) that significantly helps your work, you MUST: 1. Cite the resource (URL, ChatGPT, etc.) in a comment 2. Clearly explain how your code differs from the source 3. Explain why you needed the assistance **Failure to properly cite sources puts you at risk of:** - Being brought before the Board of Review - Having your final grade lowered - Potential course failure Remember: ChatGPT can be an invaluable learning aid, but it must be used responsibly and with proper attribution. :::warning 🚧 **API Documentation vs ChatGPT** - Always prefer official API documentation over AI responses - AI can be wrong or outdated - Use AI to help understand concepts, not as primary reference - When in doubt, trust the official documentation ::: ## Save Your Work - Exercise 3 Verify what files are uncommited: ```bash git status ``` Stage your changes (This should be the file shown in `git status` as modified) Feel free to use a different message as long as it's descriptive ```bash git add src/main/java/jam01/answers.txt ``` Commit your work ```bash git commit -m "jam01: Complete API exploration exercise" ``` Your working directory should be clean. *You can also push your changes to your remote repository on GitLab when you're ready. You really only need to push your work once you are completed with a jam, but it never hurts to push your commits more often. You never know when something might happen to your local machine - if you push after each commit, you'll have an easy remote backup!* > 🔍 **Checkpoint**: Before continuing, verify: > > - All questions in answers.txt are completed (3.1-3.8) > - Your answers cite the specific API documentation > - You can navigate to Math.PI in the documentation > - Your answers.txt file is committed