Add documentation for IonReader.close() method (#1081)

Fixes #1059: Make IonReader extend AutoCloseable for proper resource management

This change enhances the IonReader interface with comprehensive documentation for the
close() method to clarify resource management behavior and enable proper
try-with-resources usage. The interface already extended Closeable (which
extends AutoCloseable), but lacked explicit documentation about the close()
method contract.

Author: SnehangshuChakraborty

src/main/java/com/amazon/ion/IonReader.java

@@ -447,6 +447,31 @@ public interface IonReader
     // In particular, does this move the cursor beyond the current value?
     // Also, this could be problematic to use since other value-extraction
     // methods are read-once, so one can't look at the value before calling this.
-//    public String valueToString();
+    // public String valueToString();
+
+    /**
+     * Closes this reader and releases any system resources associated with it.
+     * <p>
+     * For readers created from an {@link java.io.InputStream}, this method will
+     * close the underlying stream. For readers created from byte arrays or strings,
+     * this method will release internal resources such as UTF-8 decoders.
+     * <p>
+     * After calling this method, the reader should not be used for any further
+     * operations. Attempting to use a closed reader may result in undefined behavior.
+     * <p>
+     * This method makes {@code IonReader} compatible with try-with-resources statements:
+     * <pre>{@code
+     * try (IonReader reader = IonReaderBuilder.standard().build(inputStream)) {
+     *     // Use the reader
+     *     while (reader.next() != null) {
+     *         // Process values
+     *     }
+     * } // Reader is automatically closed here
+     * }</pre>
+     *
+     * @throws IOException if an I/O error occurs while closing the underlying stream
+     */
+    @Override
+    void close() throws IOException;
 
 }

src/test/java/com/amazon/ion/IonReaderCloseableTest.java

@@ -0,0 +1,130 @@
+/*
+ * Copyright 2007-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * or in the "license" file accompanying this file. This file 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.
+ */
+
+package com.amazon.ion;
+
+import com.amazon.ion.system.IonReaderBuilder;
+import org.junit.Test;
+
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.io.InputStream;
+
+import static org.junit.Assert.*;
+
+/**
+ * Tests that IonReader properly implements Closeable and can be used with try-with-resources.
+ */
+public class IonReaderCloseableTest {
+
+    @Test
+    public void testIonReaderIsCloseable() {
+        // Verify that IonReader extends Closeable
+        assertTrue("IonReader should extend Closeable", 
+                   java.io.Closeable.class.isAssignableFrom(IonReader.class));
+    }
+
+    @Test
+    public void testIonReaderIsAutoCloseable() {
+        // Verify that IonReader extends AutoCloseable (through Closeable)
+        assertTrue("IonReader should extend AutoCloseable", 
+                   AutoCloseable.class.isAssignableFrom(IonReader.class));
+    }
+
+    @Test
+    public void testTryWithResourcesWithByteArray() throws IOException {
+        byte[] ionData = "hello".getBytes();
+        
+        // Test that IonReader can be used in try-with-resources
+        try (IonReader reader = IonReaderBuilder.standard().build(ionData)) {
+            assertNotNull("Reader should not be null", reader);
+            // Use the reader
+            IonType type = reader.next();
+            assertEquals("Should read a symbol", IonType.SYMBOL, type);
+            assertEquals("Should read 'hello'", "hello", reader.stringValue());
+        } // Reader should be automatically closed here
+        
+        // Test passes if no exception is thrown
+    }
+
+    @Test
+    public void testTryWithResourcesWithInputStream() throws IOException {
+        byte[] ionData = "world".getBytes();
+        InputStream inputStream = new ByteArrayInputStream(ionData);
+        
+        // Test that IonReader can be used in try-with-resources with InputStream
+        try (IonReader reader = IonReaderBuilder.standard().build(inputStream)) {
+            assertNotNull("Reader should not be null", reader);
+            // Use the reader
+            IonType type = reader.next();
+            assertEquals("Should read a symbol", IonType.SYMBOL, type);
+            assertEquals("Should read 'world'", "world", reader.stringValue());
+        } // Reader should be automatically closed here
+        
+        // Test passes if no exception is thrown
+    }
+
+    @Test
+    public void testManualClose() throws IOException {
+        byte[] ionData = "test".getBytes();
+        IonReader reader = IonReaderBuilder.standard().build(ionData);
+        
+        try {
+            assertNotNull("Reader should not be null", reader);
+            // Use the reader
+            IonType type = reader.next();
+            assertEquals("Should read a symbol", IonType.SYMBOL, type);
+            assertEquals("Should read 'test'", "test", reader.stringValue());
+        } finally {
+            // Manually close the reader
+            reader.close();
+        }
+        
+        // Test passes if no exception is thrown
+    }
+
+    @Test
+    public void testCloseWithInputStream() throws IOException {
+        byte[] ionData = "closetest".getBytes();
+        
+        // Create a custom InputStream that tracks if it was closed
+        class TrackingInputStream extends ByteArrayInputStream {
+            private boolean closed = false;
+            
+            public TrackingInputStream(byte[] buf) {
+                super(buf);
+            }
+            
+            @Override
+            public void close() throws IOException {
+                super.close();
+                closed = true;
+            }
+            
+            public boolean isClosed() {
+                return closed;
+            }
+        }
+        
+        TrackingInputStream trackingStream = new TrackingInputStream(ionData);
+        
+        try (IonReader reader = IonReaderBuilder.standard().build(trackingStream)) {
+            // Use the reader
+            reader.next();
+        } // Reader and underlying stream should be closed here
+        
+        assertTrue("Underlying InputStream should be closed", trackingStream.isClosed());
+    }
+}