From 5030a3e7155ef3e76926f8f929c658a9b8375a7a Mon Sep 17 00:00:00 2001 From: fgrochowski Date: Wed, 11 Dec 2024 11:30:38 +0100 Subject: [PATCH] docs: update inbox streaming api --- .../inboxEntryStream/InboxEntryStream.java | 58 +++++++++---------- .../InboxFileStreamWriter.java | 16 ++--- 2 files changed, 37 insertions(+), 37 deletions(-) diff --git a/privmx-endpoint-extra/src/main/java/com/simplito/java/privmx_endpoint_extra/inboxEntryStream/InboxEntryStream.java b/privmx-endpoint-extra/src/main/java/com/simplito/java/privmx_endpoint_extra/inboxEntryStream/InboxEntryStream.java index a999bcc..20c23d6 100644 --- a/privmx-endpoint-extra/src/main/java/com/simplito/java/privmx_endpoint_extra/inboxEntryStream/InboxEntryStream.java +++ b/privmx-endpoint-extra/src/main/java/com/simplito/java/privmx_endpoint_extra/inboxEntryStream/InboxEntryStream.java @@ -33,7 +33,7 @@ import java.util.stream.Collectors; /** - * Provides a streamlined process for creating and sending inbox entries + * Provides a streamlined process for creating and sending Inbox entries * with optional file attachments. *

This class simplifies interacting with the Inbox API for sending entries, * especially when dealing with multiple files. It manages the lifecycle of the entry creation @@ -65,13 +65,13 @@ private InboxEntryStream(InboxApi api, Map inbo * Creates {@link InboxEntryStream} instance ready for streaming. *

This method initializes an {@link InboxEntryStream} and prepares it for sending * an entry with the provided data. It creates an Inbox handle and sets the - * initial state of the stream to {@link State#FILES_SENT} + * initial state of the stream to {@link State#FILES_SENT}. * * @param inboxApi reference to Inbox API * @param inboxId ID of the Inbox - * @param entryStreamListener the listener for stream state changes. + * @param entryStreamListener the listener for stream state changes * @param data entry data to send - * @return instance of {@link InboxEntryStream} prepared for streaming. + * @return instance of {@link InboxEntryStream} prepared for streaming */ public static InboxEntryStream prepareEntry( InboxApi inboxApi, @@ -84,15 +84,15 @@ public static InboxEntryStream prepareEntry( /** * Creates {@link InboxEntryStream} instance ready for streaming. - *

This method initializes an {@link InboxEntryStream} and prepares it for sending an entry with + *

This method initializes an {@link InboxEntryStream} and prepares it for sending an entry with the * associated files and empty data. It creates Inbox and file handles, setting the initial state of the stream * to {@link State#PREPARED}, indicating readiness for file transfer. * * @param inboxApi reference to Inbox API * @param inboxId ID of the Inbox - * @param entryStreamListener the listener for stream state changes. - * @param filesConfig information about each entry's file to send. - * @return instance of {@link InboxEntryStream} prepared for streaming. + * @param entryStreamListener the listener for stream state changes + * @param filesConfig information about each entry's file to send + * @return instance of {@link InboxEntryStream} prepared for streaming */ public static InboxEntryStream prepareEntry( InboxApi inboxApi, @@ -114,8 +114,8 @@ public static InboxEntryStream prepareEntry( * @param inboxId ID of the Inbox * @param entryStreamListener the listener for stream state changes * @param data entry data to send - * @param filesConfig information about each entry's file to send. - * @return instance of {@link InboxEntryStream} prepared for streaming. + * @param filesConfig information about each entry's file to send + * @return instance of {@link InboxEntryStream} prepared for streaming */ public static InboxEntryStream prepareEntry( InboxApi inboxApi, @@ -132,7 +132,7 @@ public static InboxEntryStream prepareEntry( *

This method initializes an {@link InboxEntryStream} and prepares it for sending an entry with the provided data, * optional associated files, and optional encryption using the sender's private key. It creates an Inbox handle * and initializes file handles for any associated files. The initial state of the stream is determined based - * on the presence of files: if no files are provided, the state is set to {@link State#FILES_SENT}; otherwise, + * on the presence of files: if no files are provided, the state is set to {@link State#FILES_SENT}. Otherwise, * it's set to {@link State#PREPARED}, indicating readiness for file transfer. * * @param inboxApi reference to Inbox API @@ -141,7 +141,7 @@ public static InboxEntryStream prepareEntry( * @param data entry data to send * @param filesConfig information about each entry's file to send * @param userPrivKey sender's private key which can be used later to encrypt data for that sender - * @return instance of {@link InboxEntryStream} prepared for streaming. + * @return instance of {@link InboxEntryStream} prepared for streaming */ public static InboxEntryStream prepareEntry( InboxApi inboxApi, @@ -322,8 +322,8 @@ private void closeFileHandles() { *

This method should only be called after all files associated with the entry have been * successfully sent, indicated by the stream being in the {@link State#FILES_SENT} state. * - * @throws PrivmxException when method encounters an exception during call {@link InboxApi#sendEntry} method - * @throws NativeException when method encounters an unknown exception during call {@link InboxApi#sendEntry} method + * @throws PrivmxException when method encounters an exception while calling {@link InboxApi#sendEntry} method + * @throws NativeException when method encounters an unknown exception while calling {@link InboxApi#sendEntry} method * @throws IllegalStateException if the stream is not in the {@link State#FILES_SENT} state */ public synchronized void sendEntry() throws PrivmxException, NativeException, IllegalStateException { @@ -354,15 +354,15 @@ public enum State { */ FILES_SENT, /** - * Indicates that an error occurred during the process of sending files or the Entry. + * Indicates that an error occurred while sending files or the Entry. */ ERROR, /** - * Indicates that the entry has been sent successfully. + * Indicates that the entry was sent successfully. */ SENT, /** - * Indicates that the {@link InboxEntryStream} has been canceled. + * Indicates that the {@link InboxEntryStream} was canceled. */ ABORTED } @@ -419,7 +419,7 @@ public FileInfo( /** * Interface for listening to state changes and exchanging data with an {@link InboxEntryStream} instance. *

- * This interface provides callbacks for various events that occur during the lifecycle of an inbox entry stream, + * This interface provides callbacks for various events that occur during the lifecycle of an Inbox entry stream, * such as starting and ending file sending, requesting file chunks, handling errors, and updating the stream state. *

* Implement this interface to monitor and interact with the entry stream. @@ -429,14 +429,14 @@ public abstract static class EntryStreamListener { /** * Override this method to handle when file start sending. * - * @param file information about the file being sent + * @param file information about the sent file */ public void onStartFileSending(FileInfo file) { } /** - * Override this method to handle when file has been send successfully. + * Override this method to handle when file was sent successfully. * * @param file information about the sent file */ @@ -449,20 +449,20 @@ public void onEndFileSending(FileInfo file) { * and the stream requests a chunk of the file to send. *

This method should return the next chunk of the file. *

Returning {@code null} will cause a - * {@link NullPointerException} during file sending and stop the {@link InboxEntryStream} instance with + * {@link NullPointerException} while sending the file and stop the {@link InboxEntryStream} instance with * the state {@link State#ERROR}. * - * @param file info about file for which chunk is requested - * @return next chunk of file. + * @param file info about the file, which chunk is requested + * @return next chunk of the file */ public byte[] onNextChunkRequest(FileInfo file) { return null; } /** - * Override this method to handle event when each chunk of a file has been sent successfully. + * Override this method to handle event when each chunk of a file was sent successfully. * - * @param file information about the file for which the chunk was processed + * @param file information about the file, which chunk was processed * @param processedBytes accumulated size of sent data */ public void onFileChunkProcessed(FileInfo file, long processedBytes) { @@ -470,19 +470,19 @@ public void onFileChunkProcessed(FileInfo file, long processedBytes) { } /** - * Override this method to handle event when some error occurs during file sending. + * Override this method to handle event when an error occurs while sending files. * * @param file information about the file that caused the error - * @param throwable exception that occurred during file sending + * @param throwable exception that occurred while sending files */ public void onErrorDuringSending(FileInfo file, Throwable throwable) { } /** - * Override this method to handle event when some error occurs during creating entry. + * Override this method to handle event when an error occurs while creating entry. * - * @param throwable exception that occurred during entry creation + * @param throwable exception that occurred while creating an entry */ public void onError(Throwable throwable) { diff --git a/privmx-endpoint-extra/src/main/java/com/simplito/java/privmx_endpoint_extra/inboxFileStream/InboxFileStreamWriter.java b/privmx-endpoint-extra/src/main/java/com/simplito/java/privmx_endpoint_extra/inboxFileStream/InboxFileStreamWriter.java index 3259418..b65d851 100644 --- a/privmx-endpoint-extra/src/main/java/com/simplito/java/privmx_endpoint_extra/inboxFileStream/InboxFileStreamWriter.java +++ b/privmx-endpoint-extra/src/main/java/com/simplito/java/privmx_endpoint_extra/inboxFileStream/InboxFileStreamWriter.java @@ -59,14 +59,14 @@ public static InboxFileStreamWriter createFile( /** * Writes data to Inbox file. * - * @param inboxHandle the handle of an Inbox to write to + * @param inboxHandle the handle of the Inbox to write to * @param data data to write (the recommended size of data chunk is {@link InboxFileStream#OPTIMAL_SEND_SIZE}) * @throws PrivmxException if there is an error while writing chunk * @throws NativeException if there is an unknown error while writing chunk * @throws IllegalStateException when inboxApi is not initialized or there's no connection * @throws IOException when {@code this} is closed - * @throws PrivmxException when method encounters an exception during execution of {@link InboxApi#writeToFile} - * @throws NativeException when method encounters an unknown exception during execution of {@link InboxApi#writeToFile} + * @throws PrivmxException when method encounters an exception while executing {@link InboxApi#writeToFile} + * @throws NativeException when method encounters an unknown exception while executing {@link InboxApi#writeToFile} * @throws IllegalStateException when {@link #inboxApi} is closed */ public void write(long inboxHandle, byte[] data) throws PrivmxException, NativeException, IllegalStateException, IOException { @@ -80,8 +80,8 @@ public void write(long inboxHandle, byte[] data) throws PrivmxException, NativeE * * @param inboxHandle the handle of an Inbox to write to * @param inputStream the {@link InputStream} to read data from - * @throws PrivmxException when method encounters an exception during execution of {@link InboxApi#writeToFile} - * @throws NativeException when method encounters an unknown exception during execution of {@link InboxApi#writeToFile} + * @throws PrivmxException when method encounters an exception while executing {@link InboxApi#writeToFile} + * @throws NativeException when method encounters an unknown exception while executing {@link InboxApi#writeToFile} * @throws IllegalStateException when {@link #inboxApi} is closed * @throws IOException when {@link InputStream#read} thrown exception */ @@ -92,11 +92,11 @@ public void writeStream(long inboxHandle, InputStream inputStream) throws Privmx /** * Writes data from an {@link InputStream} to an Inbox file. * - * @param inboxHandle the handle of an Inbox to write to + * @param inboxHandle the handle of the Inbox to write to * @param inputStream the {@link InputStream} to read data from * @param streamController an optional controller for monitoring and controlling the write operation. - * @throws PrivmxException when method encounters an exception during execution of {@link InboxApi#writeToFile} - * @throws NativeException when method encounters an unknown exception during execution of {@link InboxApi#writeToFile} + * @throws PrivmxException when method encounters an exception while executing {@link InboxApi#writeToFile} + * @throws NativeException when method encounters an unknown exception while executing {@link InboxApi#writeToFile} * @throws IllegalStateException when {@link #inboxApi} is closed * @throws IOException when {@link InputStream#read} thrown exception */