improve

Author: kearfy

src/main/java/com/surrealdb/FileRef.java

@@ -3,6 +3,9 @@
 /**
  * Reference to a file stored in a SurrealDB bucket. Obtained from
  * {@link Value#getFile()} when {@link Value#isFile()} is true.
+ * 
+ * Valid only for the lifetime of the {@link Value} it was obtained from; do
+ * not retain a reference after that Value is no longer in use.
  */
 public class FileRef extends Native {
 

src/main/java/com/surrealdb/LiveNotification.java

@@ -25,7 +25,12 @@ public String getAction() {
 		return action;
 	}
 
-	/** The record value (content) for this notification. */
+	/**
+	 * The record value (content) for this notification. May be null when the
+	 * notification does not include record content (e.g. some server events).
+	 *
+	 * @return the record value, or null
+	 */
 	public Value getValue() {
 		return value;
 	}

src/main/java/com/surrealdb/LiveStream.java

@@ -4,10 +4,10 @@
 
 /**
  * Blocking iterator over live query notifications. Call {@link #next()} in a
- * loop and {@link #close()} when done (or use try-with-resources if we add
- * AutoCloseable).
+ * loop and {@link #close()} when done. Implements {@link AutoCloseable} for
+ * use in try-with-resources.
  */
-public class LiveStream {
+public class LiveStream implements AutoCloseable {
 
 	static {
 		Loader.loadNative();
@@ -35,6 +35,7 @@ public Optional<LiveNotification> next() {
 	/**
 	 * Releases the live query and stops receiving notifications. Idempotent.
 	 */
+	@Override
 	public void close() {
 		if (handle != 0) {
 			releaseNative(handle);

src/main/java/com/surrealdb/Native.java

@@ -1,5 +1,11 @@
 package com.surrealdb;
 
+/**
+ * Base for types backed by a native pointer. Instances are only valid for the
+ * lifetime of the native resource (e.g. the parent {@link Value} or connection
+ * they were obtained from). Using an instance after the underlying resource
+ * has been released may cause undefined behavior or native errors.
+ */
 public abstract class Native {
 
 	// Unique internal ptr used by the native library to locate the SurrealDB

src/main/java/com/surrealdb/Transaction.java

@@ -23,7 +23,8 @@ public class Transaction extends Native {
 
 	/**
 	 * Commits the transaction. After this call, the transaction is completed and
-	 * must not be used.
+	 * must not be used. On failure the native layer throws; the return value is
+	 * only true on success.
 	 */
 	public void commit() {
 		commit(getPtr());
@@ -32,7 +33,8 @@ public void commit() {
 
 	/**
 	 * Cancels (rolls back) the transaction. After this call, the transaction is
-	 * completed and must not be used.
+	 * completed and must not be used. On failure the native layer throws; the
+	 * return value is only true on success.
 	 */
 	public void cancel() {
 		cancel(getPtr());

src/main/java/com/surrealdb/signin/BearerCredential.java

@@ -1,5 +1,7 @@
 package com.surrealdb.signin;
 
+import java.util.Objects;
+
 /**
  * Credential that authenticates the session with an existing access token (e.g.
  * JWT). Use with {@link com.surrealdb.Surreal#signin(Credential)} to set the
@@ -13,10 +15,11 @@ public class BearerCredential implements Credential {
 	 * Creates a bearer credential with the given access token.
 	 *
 	 * @param token
-	 *            the access token (JWT) to use for authentication
+	 * the access token (JWT) to use for authentication; must not be
+	 * null
 	 */
 	public BearerCredential(String token) {
-		this.token = token;
+		this.token = Objects.requireNonNull(token, "token");
 	}
 
 	/**

src/main/java/com/surrealdb/signin/RecordCredential.java

@@ -1,5 +1,7 @@
 package com.surrealdb.signin;
 
+import java.util.Objects;
+
 /**
  * Credentials for signing up or signing in as a record user (record access
  * method). Used with {@link com.surrealdb.Surreal#signup(RecordCredential)} and
@@ -14,7 +16,8 @@
  * <p>
  * The params object is serialized and sent as the signup/signin variables (e.g.
  * email, password). It must be a type that can be converted to a SurrealDB
- * value (e.g. Map, POJO, or primitive).
+ * value (e.g. Map, POJO, or primitive). May be null; null is sent as SurrealDB
+ * null.
  */
 public class RecordCredential implements Credential {
 
@@ -39,7 +42,7 @@ public class RecordCredential implements Credential {
 	public RecordCredential(String namespace, String database, String access, Object params) {
 		this.namespace = namespace;
 		this.database = database;
-		this.access = access;
+		this.access = Objects.requireNonNull(access, "access");
 		this.params = params;
 	}
 
@@ -58,7 +61,7 @@ public RecordCredential(String namespace, String database, String access, Object
 	public RecordCredential(String access, Object params) {
 		this.namespace = null;
 		this.database = null;
-		this.access = access;
+		this.access = Objects.requireNonNull(access, "access");
 		this.params = params;
 	}
 

src/test/java/com/surrealdb/CredentialTests.java

@@ -213,6 +213,16 @@ void signup_withRecordShortConstructor_hasNullNsDb() {
 		assertEquals(Collections.singletonMap("a", 1), r.getParams());
 	}
 
+	@Test
+	void recordCredential_nullAccess_throws() {
+		Throwable e1 = assertThrows(NullPointerException.class,
+				() -> new RecordCredential("ns", "db", null, params("email", "a@b.com", "pass", "p")));
+		assertNotNull(e1.getMessage());
+		Throwable e2 = assertThrows(NullPointerException.class,
+				() -> new RecordCredential(null, params("email", "a@b.com", "pass", "p")));
+		assertNotNull(e2.getMessage());
+	}
+
 	@Test
 	void token_hasAccessAndOptionalRefresh() {
 		Token t = new Token("access_jwt", null);
@@ -230,6 +240,12 @@ void bearer_holdsToken() {
 		assertEquals("my_jwt", b.getToken());
 	}
 
+	@Test
+	void bearerCredential_nullToken_throws() {
+		Throwable e = assertThrows(NullPointerException.class, () -> new BearerCredential(null));
+		assertNotNull(e.getMessage());
+	}
+
 	@Test
 	void authenticate_returnsThis() {
 		try (Surreal surreal = new Surreal()) {

src/test/java/com/surrealdb/ExportImportTests.java

@@ -2,8 +2,10 @@
 
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.nio.file.Paths;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import org.junit.jupiter.api.Test;
 
@@ -37,4 +39,19 @@ void exportAndImportRoundTrip() throws Exception {
 			Files.deleteIfExists(dir);
 		}
 	}
+
+	@Test
+	void import_missingFile_returnsFalseOrThrows() {
+		try (Surreal surreal = new Surreal()) {
+			surreal.connect("memory").useNs("test").useDb("test");
+			Path missing = Paths.get("nonexistent_" + System.nanoTime() + ".surql");
+			try {
+				boolean imported = surreal.import_(missing.toString());
+				assertFalse(imported, "import of missing file should return false or throw");
+			} catch (SurrealException e) {
+				// expected when server throws instead of returning false
+				assertTrue(e.getMessage() != null && !e.getMessage().isEmpty());
+			}
+		}
+	}
 }

src/test/java/com/surrealdb/LiveQueryTests.java

@@ -5,6 +5,7 @@
 
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
+import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 
 import com.surrealdb.pojos.Person;
@@ -19,27 +20,28 @@ public class LiveQueryTests {
 	void selectLiveReturnsLiveStream() {
 		try (Surreal surreal = new Surreal()) {
 			surreal.connect("memory").useNs("test").useDb("test");
-			LiveStream stream = surreal.selectLive("person");
-			assertNotNull(stream);
-			stream.close();
+			try (LiveStream stream = surreal.selectLive("person")) {
+				assertNotNull(stream);
+			}
 		}
 	}
 
 	@Test
 	void liveStreamNextCanBlockAndClose() throws Exception {
+		AtomicReference<Optional<LiveNotification>> result = new AtomicReference<>();
 		try (Surreal surreal = new Surreal()) {
 			surreal.connect("memory").useNs("test").useDb("test");
 			surreal.create(Person.class, "person", Helpers.tobie);
-			LiveStream stream = surreal.selectLive("person");
-			assertNotNull(stream);
-			// next() blocks until a notification or close; run in background and close
-			// after short timeout
-			AtomicReference<Optional<LiveNotification>> result = new AtomicReference<>();
-			Thread consumer = new Thread(() -> result.set(stream.next()));
-			consumer.setDaemon(true);
-			consumer.start();
-			Thread.sleep(500);
-			stream.close();
+			Thread consumer;
+			try (LiveStream stream = surreal.selectLive("person")) {
+				assertNotNull(stream);
+				// next() blocks until a notification or close; run in background and close
+				// after short timeout
+				consumer = new Thread(() -> result.set(stream.next()));
+				consumer.setDaemon(true);
+				consumer.start();
+				Thread.sleep(500);
+			}
 			consumer.join(2000);
 			assertNotNull(result.get());
 		}
@@ -49,11 +51,35 @@ void liveStreamNextCanBlockAndClose() throws Exception {
 	void liveStreamCloseReleases() {
 		try (Surreal surreal = new Surreal()) {
 			surreal.connect("memory").useNs("test").useDb("test");
-			LiveStream stream = surreal.selectLive("person");
-			stream.close();
-			// No exception; closing again or using after close is undefined but we don't
-			// crash
+			try (LiveStream stream = surreal.selectLive("person")) {
+				// No exception; closing again or using after close is undefined but we don't
+				// crash
+			}
 			assertTrue(true);
 		}
 	}
+
+	@Test
+	void liveStreamTryWithResources() {
+		try (Surreal surreal = new Surreal()) {
+			surreal.connect("memory").useNs("test").useDb("test");
+			try (LiveStream stream = surreal.selectLive("person")) {
+				assertNotNull(stream);
+			}
+			// stream closed automatically; no leak
+		}
+	}
+
+	/**
+	 * Placeholder for future Surreal.kill(liveQueryId) support. The query ID is
+	 * available from {@link LiveNotification#getQueryId()}, but the Java client
+	 * does not yet expose kill(). Use {@link LiveStream#close()} to stop a live
+	 * query.
+	 */
+	@Test
+	@Disabled("Surreal.kill(liveQueryId) not yet in Java API")
+	void killLiveQuery_byQueryId() {
+		// When kill(uuid) is added: start live query, get queryId from first
+		// notification or API, call surreal.kill(queryId), assert stream ends.
+	}
 }