From 77ea70f4e60b66f72fe5de0c561d1ff54e09d054 Mon Sep 17 00:00:00 2001 From: Konrad Neitzel Date: Wed, 2 Apr 2025 22:09:02 +0200 Subject: [PATCH] Refactor and expand core functionalities with new modules Added robust utility modules: Tone generation, image scaling, and sound tone mapping. Developed an encryption domain with new abstractions. Updated and annotated the SQL query class for clarity and functionality. Removed unused `@Config` annotation. --- .../de/neitzel/core/image/ImageScaler.java | 155 ++ .../inject/InjectableComponentScanner.java | 188 +- .../core/inject/annotation/Component.java | 16 + .../core/inject/annotation/Config.java | 12 - .../de/neitzel/core/sound/ToneGenerator.java | 69 + .../java/de/neitzel/core/sound/ToneTable.java | 198 ++ .../main/java/de/neitzel/core/sql/Query.java | 171 +- .../neitzel/core/sql/TrimmingResultSet.java | 1858 ++++++++++------- encryption/pom.xml | 46 + .../de/neitzel/encryption/BaseAlphabet.java | 41 + .../de/neitzel/encryption/FF1Encryption.java | 140 ++ .../de/neitzel/encryption/MainAlphabet.java | 48 + .../de/neitzel/encryption/MainDomain.java | 31 + fx/pom.xml | 30 +- net/pom.xml | 49 + .../java/de/neitzel/net/imap/ImapAccount.java | 128 ++ .../neitzel/net/imap/ImapAccountMonitor.java | 256 +++ .../de/neitzel/net/imap/ImapListener.java | 17 + .../de/neitzel/net/imap/NewEmailEvent.java | 48 + .../de/neitzel/net/mail/MessageUtils.java | 82 + pom.xml | 75 +- 21 files changed, 2754 insertions(+), 904 deletions(-) create mode 100644 core/src/main/java/de/neitzel/core/image/ImageScaler.java delete mode 100644 core/src/main/java/de/neitzel/core/inject/annotation/Config.java create mode 100644 core/src/main/java/de/neitzel/core/sound/ToneGenerator.java create mode 100644 core/src/main/java/de/neitzel/core/sound/ToneTable.java create mode 100644 encryption/pom.xml create mode 100644 encryption/src/main/java/de/neitzel/encryption/BaseAlphabet.java create mode 100644 encryption/src/main/java/de/neitzel/encryption/FF1Encryption.java create mode 100644 encryption/src/main/java/de/neitzel/encryption/MainAlphabet.java create mode 100644 encryption/src/main/java/de/neitzel/encryption/MainDomain.java create mode 100644 net/pom.xml create mode 100644 net/src/main/java/de/neitzel/net/imap/ImapAccount.java create mode 100644 net/src/main/java/de/neitzel/net/imap/ImapAccountMonitor.java create mode 100644 net/src/main/java/de/neitzel/net/imap/ImapListener.java create mode 100644 net/src/main/java/de/neitzel/net/imap/NewEmailEvent.java create mode 100644 net/src/main/java/de/neitzel/net/mail/MessageUtils.java diff --git a/core/src/main/java/de/neitzel/core/image/ImageScaler.java b/core/src/main/java/de/neitzel/core/image/ImageScaler.java new file mode 100644 index 0000000..bfa7ac2 --- /dev/null +++ b/core/src/main/java/de/neitzel/core/image/ImageScaler.java @@ -0,0 +1,155 @@ +package de.neitzel.core.image; + +import javax.imageio.ImageIO; +import java.awt.*; +import java.awt.image.BufferedImage; +import java.io.ByteArrayInputStream; +import java.io.ByteArrayOutputStream; +import java.io.InputStream; + +/** + * Utility class for scaling images while maintaining the aspect ratio. + * Provides methods to create scaled images either as byte arrays or InputStreams. + */ +public class ImageScaler { + + /** + * Private constructor to prevent instantiation of this utility class. + */ + private ImageScaler() { + throw new UnsupportedOperationException("Utility class cannot be instantiated"); + } + + /** + * Specifies the target image format for scaling operations. + * + * This variable defines the file format that will be used when writing + * or encoding the scaled image. The format must be compatible with + * Java's ImageIO framework (e.g., "png", "jpg", "bmp"). + * + * In this case, the target format is set to "png", allowing images + * to be scaled and saved or returned as PNG files. It ensures + * consistent output format across the image scaling methods in the class. + */ + private static String TARGET_FORMAT="png"; + + /** + * Creates a scaled image from the given byte array representation and returns it as a byte array. + * + * If enforceSize is set to false, the given dimensions are used as maximum values for scaling. + * The resulting image may retain its aspect ratio and be smaller than the specified dimensions. + * If enforceSize is true, the resulting image will match the exact dimensions, potentially adding + * transparent areas on the top/bottom or right/left sides to maintain the original aspect ratio. + * + * @param originalImageBytes The byte array representing the original image. + * @param width The (maximum) width of the target image. + * @param height The (maximum) height of the target image. + * @param enforceSize A flag indicating whether the resulting image should strictly adhere to specified dimensions. + * If false, the image will retain its aspect ratio without empty borders. + * @return A byte array representing the scaled image, or null if the operation failed or the input was invalid. + */ + public static byte[] createScaledImage(final byte[] originalImageBytes, final int width, final int height, final boolean enforceSize) { + // Validation + if (originalImageBytes == null) return null; + if (originalImageBytes.length==0) return null; + + try { + // Create the image from a byte array. + BufferedImage originalImage = ImageIO.read(new ByteArrayInputStream(originalImageBytes)); + return createScaledImage(originalImage, width, height, enforceSize); + } catch (Exception ex) { + return null; + } + } + + /** + * Scales an image provided as a byte array to the specified dimensions and returns an InputStream of the scaled image. + * + * The scaling behavior is determined by the enforceSize parameter: + * - If enforceSize is false, the provided dimensions are treated as maximum values, maintaining the original aspect ratio. + * - If enforceSize is true, the resulting image will match the exact dimensions, potentially with transparent borders to keep the original aspect ratio. + * + * @param originalImageBytes The byte array representing the original image. + * @param width The (maximum) width of the target scaled image. + * @param height The (maximum) height of the target scaled image. + * @param enforceSize A flag indicating whether to enforce the exact scaled dimensions. If false, the resulting image retains its aspect ratio. + * @return An InputStream representing the scaled image, or null if the operation fails or the input image is invalid. + */ + public static InputStream scaledImage(final byte[] originalImageBytes, final int width, final int height, final boolean enforceSize) { + // Get the scaled image. + byte[] bytes = createScaledImage(originalImageBytes, width, height, enforceSize); + + // Validation of result. + if (bytes == null || bytes.length == 0) return null; + + // Return new InputStream. + return new ByteArrayInputStream(bytes); + } + + /** + * Creates a scaled version of the given {@link BufferedImage} and returns it as a byte array. + * + * The scaling behavior is determined by the enforceSize parameter: + * - If enforceSize is false, the provided dimensions are treated as maximum values, and the image + * will maintain its original aspect ratio. The resulting image may be smaller than the specified + * dimensions. + * - If enforceSize is true, the resulting image will match the exact specified dimensions, potentially + * adding transparent padding to fit the aspect ratio. + * + * @param originalImage The original image to be scaled. Must not be null. + * @param width The specified (maximum) width of the scaled image. + * @param height The specified (maximum) height of the scaled image. + * @param enforceSize A flag indicating whether the scaled image should strictly conform to the specified + * dimensions. If true, the image may include transparent areas to maintain the aspect ratio. + * @return A byte array representing the scaled image, or null if the scaling operation fails or the input image is invalid. + */ + protected static byte[] createScaledImage(final BufferedImage originalImage, final int width, final int height, final boolean enforceSize) { + // Validation + if (originalImage == null) return null; + + try { + // Get the scale factor. + double scaleWidth = (double) width / (double) originalImage.getWidth(); + double scaleHeight = (double) height / (double) originalImage.getHeight(); + + double scaleFactor; + if (scaleWidth > scaleHeight) { + scaleFactor = scaleHeight; + } else { + scaleFactor = scaleWidth; + } + + // Calculate target size of scaled image. + int newHeight = (int) (scaleFactor * originalImage.getHeight()); + int newWidth = (int) (scaleFactor * originalImage.getWidth()); + + // Cooordinates of new picture and size of new picture. + int x, y, usedHeight, usedWidth; + if (enforceSize) { + usedHeight = height; + usedWidth = width; + x = (width - newWidth) / 2; + y = (height - newHeight) / 2; + } else { + x = 0; + y = 0; + usedHeight = newHeight; + usedWidth = newWidth; + } + + // Scale the image + BufferedImage scaledImage = new BufferedImage(usedWidth, usedHeight, BufferedImage.TYPE_INT_ARGB); + Graphics2D graphics = scaledImage.createGraphics(); + graphics.setRenderingHint(RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BILINEAR); + graphics.drawImage(originalImage, x, y, newWidth, newHeight, null); + + // Get the bytes of the image + try (ByteArrayOutputStream stream = new ByteArrayOutputStream()) { + ImageIO.write(scaledImage, TARGET_FORMAT, stream); + return stream.toByteArray(); + } + } catch (Exception ex) { + return null; + } + } +} \ No newline at end of file diff --git a/core/src/main/java/de/neitzel/core/inject/InjectableComponentScanner.java b/core/src/main/java/de/neitzel/core/inject/InjectableComponentScanner.java index 8f0092a..17f73fa 100644 --- a/core/src/main/java/de/neitzel/core/inject/InjectableComponentScanner.java +++ b/core/src/main/java/de/neitzel/core/inject/InjectableComponentScanner.java @@ -8,30 +8,93 @@ import java.util.*; import java.util.stream.Collectors; /** - * InjectableComponents scans a package for classes annotated with {@link Component}. - * It determines which components can be instantiated and manages type mappings for dependency injection. + * InjectableComponentScanner is responsible for scanning packages to detect classes annotated + * with @FXMLComponent and analyzing their compatibility for instantiation and dependency injection. + * The resulting analysis identifies unique and shared interfaces/superclasses as well as + * potentially instantiable components, collecting relevant errors if instantiation is not feasible. */ public class InjectableComponentScanner { - /** Set of all detected @FXMLComponent classes within the given package. */ + /** + * A set that stores classes annotated with {@code @Component}, representing + * FXML-compatible components detected during the scanning process. + * These components are used as part of the dependency injection mechanism + * within the {@code InjectableComponentScanner}. + * + * The {@code fxmlComponents} set is populated during the component scanning + * phase by identifying all classes within a specified package hierarchy + * annotated with the {@code @Component} annotation. These classes serve + * as the primary source for further analysis, resolution, and instantiation + * in the scanning workflow. + * + * This field is immutable, ensuring thread safety and consistent state + * throughout the lifetime of the {@code InjectableComponentScanner}. + */ private final Set> fxmlComponents = new HashSet<>(); - /** Set of all superclasses and interfaces that are implemented by multiple @FXMLComponent classes. */ + /** + * A set of component types that are not uniquely associated with a single implementation. + * + * This collection is populated during the analysis of discovered components to identify + * types that have multiple implementations, preventing them from being uniquely resolved. + * For example, if multiple components implement the same interface, that interface will be + * added to this set. + * + * It is primarily used during the component registration process to avoid ambiguities + * in the dependency injection system, ensuring that only resolvable, uniquely identifiable + * components can be instantiated and injected. + */ private final Set> notUniqueTypes = new HashSet<>(); - /** Map of unique superclasses/interfaces to a single corresponding @FXMLComponent class. */ + /** + * A mapping of unique super types to their corresponding component classes. + * The key represents a super type (interface or abstract class), and the value + * is the specific implementation or subclass that is uniquely identified among + * the scanned components. + * + * This map is populated during the component analysis process. For each super type + * in the scanned components, if exactly one implementation is found, it is + * considered unique and added to this mapping. In case multiple implementations + * exist for a given super type, it is excluded from this map and classified as + * a non-unique type. + * + * This mapping is utilized for resolving dependencies and determining which components + * can be instantiated based on unique type information. + */ private final Map, Class> uniqueTypeToComponent = new HashMap<>(); - /** Map of instantiable @FXMLComponent classes and their corresponding interfaces/superclasses (if unique). */ + /** + * A mapping of components that can be instantiated with their corresponding types. + * This map links a component's class (key) to the specific implementation class (value) + * that can be instantiated. The entries are resolved through the scanning and analysis + * of available component types, ensuring that only components with resolvable + * dependencies are included. + * + * This field is part of the dependency injection process, where components annotated + * with {@code @Component} or similar annotations are scanned, analyzed, and registered. + * The resolution process checks if a component can be instantiated based on its + * constructor dependencies being resolvable using known types or other registered components. + */ private final Map, Class> instantiableComponents = new HashMap<>(); - /** List of error messages generated when resolving component instantiability. */ + /** + * A list of error messages encountered during the scanning and analysis + * of components in the dependency injection process. + * + * This list is populated when components cannot be resolved due to issues + * such as multiple implementations of a superclass or interface, + * unmet construction requirements, or unresolved dependencies. + * + * Errors added to this list provide detailed descriptions of the specific + * issues that prevent certain components from being instantiated correctly. + */ private final List errors = new ArrayList<>(); /** - * Constructs an InjectableComponents instance and scans the given package for @FXMLComponent classes. + * Initializes a new instance of the {@code InjectableComponentScanner} class, which scans for injectable + * components within the specified base package and resolves the set of recognizable and instantiable components. * - * @param basePackage The base package to scan for @FXMLComponent classes. + * @param basePackage the base package to scan for injectable components */ public InjectableComponentScanner(String basePackage) { scanForComponents(basePackage); @@ -40,9 +103,10 @@ public class InjectableComponentScanner { } /** - * Scans the specified package for classes annotated with @FXMLComponent. + * Scans the specified base package for classes annotated with {@link Component}. + * Identified component classes are added to a collection for further processing. * - * @param basePackage The package to scan. + * @param basePackage the package to scan for component annotations */ private void scanForComponents(String basePackage) { Reflections reflections = new Reflections(basePackage); @@ -50,7 +114,23 @@ public class InjectableComponentScanner { } /** - * Analyzes the collected @FXMLComponent classes to determine unique and non-unique superclasses/interfaces. + * Analyzes component types within the injected components and classifies them based on their + * inheritance hierarchy and relationships. + * + * This method performs the following operations: + * 1. Maps each component to all of its superclasses and interfaces. + * 2. Identifies which superclasses or interfaces have multiple implementing components. + * 3. Populates: + * - A list of superclasses or interfaces that are not uniquely linked to a single component. + * - A map where unique superclasses or interfaces are associated with a specific implementing component. + * + * The mappings are built using the following data structures: + * - A map from superclasses/interfaces to the list of components that implement or extend them. + * - A list of non-unique types where multiple components exist for the same superclass or interface. + * - A map of unique superclasses/interfaces to their corresponding component. + * + * This method is a key part of the component scanning and resolution process, facilitating + * the identification of potential instantiation ambiguities or conflicts. */ private void analyzeComponentTypes() { Map, List>> superTypesMap = new HashMap<>(); @@ -76,8 +156,23 @@ public class InjectableComponentScanner { } /** - * Determines which @FXMLComponent classes can be instantiated based on known dependencies. - * It registers valid components and collects errors for components that cannot be instantiated. + * Resolves components from the set of scanned classes that can be instantiated based on their constructors + * and existing known types. The method iteratively processes classes to identify those whose dependencies + * can be satisfied, marking them as resolved and registering them alongside their supertypes. + * + * If progress is made during a pass (i.e., a component is resolved), the process continues until no more + * components can be resolved. Any components that remain unresolved are recorded for further inspection. + * + * The resolved components are stored in a map where each type and its supertypes are associated + * with the component class itself. This map allows for subsequent lookups when verifying dependency satisfiability. + * + * If unresolved components remain after the resolution process, detailed instantiation errors are collected + * for debugging or logging purposes. + * + * This method depends on the following utility methods: + * - {@link #canInstantiate(Class, Set)}: Determines if a component can be instantiated based on existing known types. + * - {@link #registerComponentWithSuperTypes(Class, Map)}: Registers a component and its supertypes in the known types map. + * - {@link #collectInstantiationErrors(Set)}: Collects detailed error messages for unresolved components. */ private void resolveInstantiableComponents() { Set> resolved = new HashSet<>(); @@ -108,10 +203,11 @@ public class InjectableComponentScanner { } /** - * Registers a component along with its unique superclasses and interfaces in the known types map. + * Registers the given component class in the provided map. The component is registered along with all of its + * accessible superclasses and interfaces, unless those types are identified as non-unique. * - * @param component The component class. - * @param knownTypes The map of known instantiable types. + * @param component the component class to register + * @param knownTypes the map where the component and its types will be registered */ private void registerComponentWithSuperTypes(Class component, Map, Class> knownTypes) { knownTypes.put(component, component); @@ -124,11 +220,13 @@ public class InjectableComponentScanner { } /** - * Checks whether a given @FXMLComponent class can be instantiated based on known dependencies. + * Determines whether a given class can be instantiated based on its constructors and + * the provided known types. A class is considered instantiable if it has a parameterless + * constructor or if all the parameter types of its constructors are present in the known types. * - * @param component The component class to check. - * @param knownTypes Set of known instantiable types. - * @return {@code true} if the component can be instantiated, otherwise {@code false}. + * @param component the class to check for instantiation eligibility + * @param knownTypes the set of types known to be instantiable and available for constructor injection + * @return true if the class can be instantiated; false otherwise */ private boolean canInstantiate(Class component, Set> knownTypes) { for (Constructor constructor : component.getConstructors()) { @@ -141,9 +239,12 @@ public class InjectableComponentScanner { } /** - * Collects error messages for components that cannot be instantiated and adds them to the error list. + * Collects the instantiation errors for a set of unresolved classes and appends + * detailed error messages to the internal error list. This method analyzes unresolved + * components based on their constructors, determining if all required types are + * instantiable or if there are conflicting types that could prevent instantiation. * - * @param unresolved Set of components that could not be instantiated. + * @param unresolved the set of classes for which instantiation errors are collected */ private void collectInstantiationErrors(Set> unresolved) { for (Class component : unresolved) { @@ -175,10 +276,13 @@ public class InjectableComponentScanner { } /** - * Returns a comma-separated list of conflicting types that prevent instantiation. + * Identifies and retrieves a comma-separated string of conflicting types for a given component. + * A conflicting type is a parameter type in the constructor of the given component + * that is already marked as not unique within the application context. * - * @param component The component class. - * @return A string listing the conflicting types. + * @param component the class for which conflicting types need to be identified. + * @return a comma-separated string of fully qualified names of conflicting parameter types, + * or an empty string if no conflicts are found. */ private String getConflictingTypes(Class component) { return Arrays.stream(component.getConstructors()) @@ -189,10 +293,10 @@ public class InjectableComponentScanner { } /** - * Retrieves all superclasses and interfaces of a given class. + * Retrieves all superclasses and interfaces of the specified class, excluding the {@code Object} class. * - * @param clazz The class to analyze. - * @return A set of all superclasses and interfaces of the given class. + * @param clazz the class for which to retrieve all superclasses and interfaces + * @return a set of all superclasses and interfaces implemented by the specified class */ private Set> getAllSuperTypes(Class clazz) { Set> result = new HashSet<>(); @@ -208,36 +312,46 @@ public class InjectableComponentScanner { } /** - * Returns a map of instantiable @FXMLComponent classes and their associated interfaces/superclasses. + * Retrieves a map of classes representing component types to their corresponding instantiable implementations. * - * @return A map of instantiable components. + * @return A map where the key is a class type and the value is the corresponding class implementation + * that can be instantiated. */ public Map, Class> getInstantiableComponents() { return instantiableComponents; } /** - * Returns the set of non-unique types (superclasses/interfaces with multiple implementations). + * Retrieves a set of types that have multiple implementations, making them + * non-unique. These types could not be uniquely resolved during the + * component scanning and analysis process. * - * @return A set of non-unique types. + * @return a set of classes representing the types that have multiple + * implementations and cannot be resolved uniquely */ public Set> getNotUniqueTypes() { return notUniqueTypes; } /** - * Returns the map of unique types to corresponding @FXMLComponent implementations. + * Returns a mapping of types to their unique component implementations. + * This map includes only those types that have a single corresponding component + * implementation, ensuring no ambiguity in resolution. * - * @return A map of unique types. + * @return a map where the keys are types (e.g., interfaces or superclasses) + * and the values are their unique component implementations. */ public Map, Class> getUniqueTypeToComponent() { return uniqueTypeToComponent; } /** - * Returns a list of errors encountered during instantiation resolution. + * Retrieves a list of error messages recorded during the scanning and analysis process. + * The errors typically indicate issues such as components that cannot be instantiated due to + * missing dependencies, unresolvable component types, or multiple implementations of a type + * that are not uniquely resolved. * - * @return A list of error messages. + * @return a list of error messages explaining the issues encountered. */ public List getErrors() { return errors; diff --git a/core/src/main/java/de/neitzel/core/inject/annotation/Component.java b/core/src/main/java/de/neitzel/core/inject/annotation/Component.java index fd4a3b0..73cb855 100644 --- a/core/src/main/java/de/neitzel/core/inject/annotation/Component.java +++ b/core/src/main/java/de/neitzel/core/inject/annotation/Component.java @@ -5,6 +5,22 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +/** + * Indicates that an annotated class is a "component" within a dependency injection framework. + * Classes annotated with {@code @Component} are recognized during the component scanning process + * as candidates for instantiation and management by the dependency injection framework. + * + * This annotation is typically used on classes that represent application-specific components, + * such as service implementations, controllers, or other objects intended to be instantiated + * and injected into other components during runtime. + * + * The annotation must be placed at the type level, and it is retained at runtime + * to allow for reflection-based scanning of classes within specified packages. + * + * Usage of this annotation assumes that there exists a component scanning mechanism + * that processes annotated classes and identifies their roles, dependencies, and hierarchy + * within the application's structure. + */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.TYPE) public @interface Component { diff --git a/core/src/main/java/de/neitzel/core/inject/annotation/Config.java b/core/src/main/java/de/neitzel/core/inject/annotation/Config.java deleted file mode 100644 index 1992bc2..0000000 --- a/core/src/main/java/de/neitzel/core/inject/annotation/Config.java +++ /dev/null @@ -1,12 +0,0 @@ -package de.neitzel.core.inject.annotation; - -import java.lang.annotation.ElementType; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; - -@Retention(RetentionPolicy.RUNTIME) -@Target(ElementType.TYPE) -public @interface Config { - String value() default ""; -} diff --git a/core/src/main/java/de/neitzel/core/sound/ToneGenerator.java b/core/src/main/java/de/neitzel/core/sound/ToneGenerator.java new file mode 100644 index 0000000..cab8df8 --- /dev/null +++ b/core/src/main/java/de/neitzel/core/sound/ToneGenerator.java @@ -0,0 +1,69 @@ +package de.neitzel.core.sound; + +import javax.sound.sampled.AudioFormat; +import javax.sound.sampled.AudioSystem; +import javax.sound.sampled.LineUnavailableException; +import javax.sound.sampled.SourceDataLine; + +/** + * The ToneGenerator class provides methods to generate and play tones. + * It allows playing tones based on frequency or predefined tone names. + */ +public class ToneGenerator { + /** + * Plays a tone based on a predefined tone name for a specified duration. + * + * @param tone The name of the tone to play. Must correspond to a predefined tone in the tone table. + * @param duration The duration of the tone in milliseconds. + * @throws LineUnavailableException If a line for audio playback cannot be opened. + */ + public static void playTone(String tone, int duration) throws LineUnavailableException { + playTone(ToneTable.getFrequency(tone), duration); + } + + /** + * Plays a tone at the specified frequency and duration. + * + * @param frequency the frequency of the tone in Hertz (Hz) + * @param duration the duration of the tone in milliseconds + * @throws LineUnavailableException if the audio line cannot be opened + */ + public static void playTone(double frequency, int duration) throws LineUnavailableException { + // Get the audio format + AudioFormat format = new AudioFormat(AudioFormat.Encoding.PCM_SIGNED, 44100, 16, 2, 4, 44100, false); + + // Open the audio line + try (SourceDataLine line = AudioSystem.getSourceDataLine(format)) { + + line.open(format); + line.start(); + + // Generate the tone data + byte[] toneBuffer = new byte[2 * duration * 44100 / 1000]; + for (int i = 0; i < toneBuffer.length; i += 2) { + double angle = i / (44100.0 / frequency) * 2.0 * Math.PI; + short sample = (short) (Math.sin(angle) * 32767); + toneBuffer[i] = (byte) (sample & 0xFF); + toneBuffer[i + 1] = (byte) ((sample >> 8) & 0xFF); + } + + // Play the tone + line.write(toneBuffer, 0, toneBuffer.length); + line.drain(); + } + } + + /** + * Plays one or more specified tones for a given duration. + * Each tone is played sequentially in the order they are provided. + * + * @param duration the duration of each tone in milliseconds + * @param tones the names of the tones to play, specified as a variable-length argument + * @throws LineUnavailableException if the audio line cannot be opened or accessed + */ + public static void playTone(int duration, String... tones) throws LineUnavailableException { + for (String tone : tones) { + playTone(tone, duration); + } + } +} diff --git a/core/src/main/java/de/neitzel/core/sound/ToneTable.java b/core/src/main/java/de/neitzel/core/sound/ToneTable.java new file mode 100644 index 0000000..a195658 --- /dev/null +++ b/core/src/main/java/de/neitzel/core/sound/ToneTable.java @@ -0,0 +1,198 @@ +package de.neitzel.core.sound; + +import java.util.HashMap; + +/** + * The ToneTable class provides a static lookup tool for associating musical tone names + * with their corresponding frequencies in hertz (Hz). It allows users to + * retrieve the frequency of a tone based on its standard notation name, + * such as "C3", "A4", or "G#5". + * + * This class can be particularly useful in applications related to sound synthesis, + * music theory, signal processing, and other audio-related domains that require precise + * frequency information for specific tones. + */ +public class ToneTable { + /** + * A static map that associates written tone names with their corresponding frequencies in hertz (Hz). + * The keys represent tone names (e.g., "C4", "D#5"), and the values are their respective frequencies. + * This map serves as a reference for converting tone names into their precise frequency values, + * which are used in applications such as tone generation or audio playback. + * + * The map is a crucial component of the ToneTable class, providing quick lookup of frequencies + * for predefined tone names. + */ + private static final HashMap toneMap = new HashMap<>(); + static { + toneMap.put("C0", 16.35); + toneMap.put("C#0", 17.32); + toneMap.put("Db0", 17.32); + toneMap.put("D0", 18.35); + toneMap.put("D#0", 19.45); + toneMap.put("Eb0", 19.45); + toneMap.put("E0", 20.60); + toneMap.put("F0", 21.83); + toneMap.put("F#0", 23.12); + toneMap.put("Gb0", 23.12); + toneMap.put("G0", 24.50); + toneMap.put("G#0", 25.96); + toneMap.put("Ab0", 25.96); + toneMap.put("A0", 27.50); + toneMap.put("A#0", 29.14); + toneMap.put("Bb0", 29.14); + toneMap.put("B0", 30.87); + toneMap.put("C1", 32.70); + toneMap.put("C#1", 34.65); + toneMap.put("Db1", 34.65); + toneMap.put("D1", 36.71); + toneMap.put("D#1", 38.89); + toneMap.put("Eb1", 38.89); + toneMap.put("E1", 41.20); + toneMap.put("F1", 43.65); + toneMap.put("F#1", 46.25); + toneMap.put("Gb1", 46.25); + toneMap.put("G1", 49.00); + toneMap.put("G#1", 51.91); + toneMap.put("Ab1", 51.91); + toneMap.put("A1", 55.00); + toneMap.put("A#1", 58.27); + toneMap.put("Bb1", 58.27); + toneMap.put("B1", 61.74); + toneMap.put("C2", 65.41); + toneMap.put("C#2", 69.30); + toneMap.put("Db2", 69.30); + toneMap.put("D2", 73.42); + toneMap.put("D#2", 77.78); + toneMap.put("Eb2", 77.78); + toneMap.put("E2", 82.41); + toneMap.put("F2", 87.31); + toneMap.put("F#2", 92.50); + toneMap.put("Gb2", 92.50); + toneMap.put("G2", 98.00); + toneMap.put("G#2", 103.83); + toneMap.put("Ab2", 103.83); + toneMap.put("A2", 110.00); + toneMap.put("A#2", 116.54); + toneMap.put("Bb2", 116.54); + toneMap.put("B2", 123.47); + toneMap.put("C3", 130.81); + toneMap.put("C#3", 138.59); + toneMap.put("Db3", 138.59); + toneMap.put("D3", 146.83); + toneMap.put("D#3", 155.56); + toneMap.put("Eb3", 155.56); + toneMap.put("E3", 164.81); + toneMap.put("F3", 174.61); + toneMap.put("F#3", 185.00); + toneMap.put("Gb3", 185.00); + toneMap.put("G3", 196.00); + toneMap.put("G#3", 207.65); + toneMap.put("Ab3", 207.65); + toneMap.put("A3", 220.00); + toneMap.put("A#3", 233.08); + toneMap.put("Bb3", 233.08); + toneMap.put("B3", 246.94); + toneMap.put("C4", 261.63); + toneMap.put("C#4", 277.18); + toneMap.put("Db4", 277.18); + toneMap.put("D4", 293.66); + toneMap.put("D#4", 311.13); + toneMap.put("Eb4", 311.13); + toneMap.put("E4", 329.63); + toneMap.put("F4", 349.23); + toneMap.put("F#4", 369.99); + toneMap.put("Gb4", 369.99); + toneMap.put("G4", 392.00); + toneMap.put("G#4", 415.30); + toneMap.put("Ab4", 415.30); + toneMap.put("A4", 440.00); + toneMap.put("A#4", 466.16); + toneMap.put("Bb4", 466.16); + toneMap.put("B4", 493.88); + toneMap.put("C5", 523.25); + toneMap.put("C#5", 554.37); + toneMap.put("Db5", 554.37); + toneMap.put("D5", 587.33); + toneMap.put("D#5", 622.25); + toneMap.put("Eb5", 622.25); + toneMap.put("E5", 659.25); + toneMap.put("F5", 698.46); + toneMap.put("F#5", 739.99); + toneMap.put("Gb5", 739.99); + toneMap.put("G5", 783.99); + toneMap.put("G#5", 830.61); + toneMap.put("Ab5", 830.61); + toneMap.put("A5", 880.00); + toneMap.put("A#5", 932.33); + toneMap.put("Bb5", 932.33); + toneMap.put("B5", 987.77); + toneMap.put("C6", 1046.50); + toneMap.put("C#6", 1108.73); + toneMap.put("Db6", 1108.73); + toneMap.put("D6", 1174.66); + toneMap.put("D#6", 1244.51); + toneMap.put("Eb6", 1244.51); + toneMap.put("E6", 1318.51); + toneMap.put("F6", 1396.91); + toneMap.put("F#6", 1479.98); + toneMap.put("Gb6", 1479.98); + toneMap.put("G6", 1567.98); + toneMap.put("G#6", 1661.22); + toneMap.put("Ab6", 1661.22); + toneMap.put("A6", 1760.00); + toneMap.put("A#6", 1864.66); + toneMap.put("Bb6", 1864.66); + toneMap.put("B6", 1975.53); + toneMap.put("C7", 2093.00); + toneMap.put("C#7", 2217.46); + toneMap.put("Db7", 2217.46); + toneMap.put("D7", 2349.32); + toneMap.put("D#7", 2489.02); + toneMap.put("Eb7", 2489.02); + toneMap.put("E7", 2637.02); + toneMap.put("F7", 2793.83); + toneMap.put("F#7", 2959.96); + toneMap.put("Gb7", 2959.96); + toneMap.put("G7", 3135.96); + toneMap.put("G#7", 3322.44); + toneMap.put("Ab7", 3322.44); + toneMap.put("A7", 3520.00); + toneMap.put("A#7", 3729.31); + toneMap.put("Bb7", 3729.31); + toneMap.put("B7", 3951.07); + toneMap.put("C8", 4186.01); + toneMap.put("C#8", 4434.92); + toneMap.put("Db8", 4434.92); + toneMap.put("D8", 4698.63); + toneMap.put("D#8", 4978.03); + toneMap.put("Eb8", 4978.03); + toneMap.put("E8", 5274.04); + toneMap.put("F8", 5587.65); + toneMap.put("F#8", 5919.91); + toneMap.put("Gb8", 5919.91); + toneMap.put("G8", 6271.93); + toneMap.put("G#8", 6644.88); + toneMap.put("Ab8", 6644.88); + toneMap.put("A8", 7040.00); + toneMap.put("A#8", 7458.62); + toneMap.put("Bb8", 7458.62); + toneMap.put("B8", 7902.13); + } + + /** + * Retrieves the frequency of the tone based on the given tone name. + * If the tone name exists in the tone map, its corresponding frequency is returned. + * Otherwise, an exception is thrown. + * + * @param toneName the name of the tone whose frequency is to be retrieved + * @return the frequency associated with the specified tone name + * @throws IllegalArgumentException if the tone name is not found in the tone map + */ + public static double getFrequency(String toneName) { + if (toneMap.containsKey(toneName)) { + return toneMap.get(toneName); + } else { + throw new IllegalArgumentException("Unknown tone name: " + toneName); + } + } +} \ No newline at end of file diff --git a/core/src/main/java/de/neitzel/core/sql/Query.java b/core/src/main/java/de/neitzel/core/sql/Query.java index e9d1bc3..ac86b59 100644 --- a/core/src/main/java/de/neitzel/core/sql/Query.java +++ b/core/src/main/java/de/neitzel/core/sql/Query.java @@ -15,14 +15,22 @@ import java.util.stream.Stream; import java.util.stream.StreamSupport; /** - * Helper class to build and execute parameterized SQL queries with factory-based result mapping. + * A generic class for managing SQL queries and their execution using JDBC. + * The class supports parameterized queries, allows loading queries from resources, + * and facilitates streaming of result sets. + * + * @param The type of the objects returned by the query. */ @Slf4j @RequiredArgsConstructor public class Query { /** - * An Integer Factory that can be used to read Integer Values of a ResultSet that only has Integers (e.g. a min oder max query) + * A factory function that extracts an Integer from the first column of a given ResultSet. + *

+ * This function is designed to facilitate the conversion of a ResultSet row into an Integer + * by accessing the value in the first column of the result set. If an SQL exception is encountered + * during the retrieval of the integer value, it is wrapped and re-thrown as a runtime exception. */ public static final Function INTEGER_FACTORY = rs -> { try { @@ -32,11 +40,42 @@ public class Query { } }; + /** + * Represents a database connection instance. + * This connection is used to interact with a database + * through executing queries and retrieving results. + * It is immutable and initialized once. + */ private final Connection connection; + + /** + * A list of ParameterSetter objects used to configure parameters. + * This collection serves as a storage for managing parameter-setting logic dynamically. + * It is initialized as an empty ArrayList and is immutable since it is declared as final. + */ private final List parameterSetters = new ArrayList<>(); + + /** + * A functional interface representing a factory method used to produce instances of type T. + * This factory is typically implemented to map rows from a {@link ResultSet} to objects of type T. + * The input parameter is a {@link ResultSet}, which provides access to database query results. + * The resulting output is an instance of type T created based on the data in the provided ResultSet. + */ private Function factory; + + /** + * Represents the text of a query. + * This variable stores the query string used for processing or execution purposes within the application. + */ private String queryText; + /** + * Executes the given SQL query using the provided database connection. + * + * @param connection the database connection to be used for executing the query + * @param query the SQL query to be executed + * @throws SQLException if a database access error occurs or the query execution fails + */ public static void execute(final Connection connection, final String query) throws SQLException { new Query(connection) .setQueryText(query) @@ -44,7 +83,10 @@ public class Query { } /** - * sets the query. + * Sets the query text for the current query instance. + * + * @param queryText the text of the query to be set + * @return the current instance of the query */ public Query setQueryText(final String queryText) { this.queryText = queryText; @@ -52,7 +94,11 @@ public class Query { } /** - * Loads the query content from a resource URL. + * Sets the query resource by loading its content from the given resource path. + * The resource content is read and stored as the query text for the query object. + * + * @param resourcePath the path to the resource file containing the query text + * @return the current Query object with the loaded query text */ public Query setQueryResource(final String resourcePath) { log.info("loading resource: {}", resourcePath); @@ -65,7 +111,11 @@ public class Query { } /** - * Replaces placeholders in the query. + * Replaces all occurrences of the specified placeholder in the query text with the provided value. + * + * @param placeholder the placeholder string to be replaced in the query text + * @param value the value to replace the placeholder with + * @return the updated Query instance with the modified query text */ public Query replace(final String placeholder, final String value) { this.queryText = this.queryText.replace(placeholder, value); @@ -74,13 +124,13 @@ public class Query { } /** - * Adds another parameter setter + * Adds a parameter to the query at the specified index with a custom setter function. * - * @param index Index of parameter in prepared statement - * @param value Value to set. - * @param setter Setter to use on prepared statement. - * @param Type of the Parameter. - * @return The Query. + * @param index The position of the parameter in the query starting from 1. + * @param value The value of the parameter to be set. + * @param setter A TriSqlFunction that defines how to set the parameter in the PreparedStatement. + * @param The type of the parameter value. + * @return The current query instance for method chaining. */ public Query addParameter(final int index, final X value, final TriSqlFunction setter) { parameterSetters.add(ps -> setter.apply(ps, index, value)); @@ -88,10 +138,10 @@ public class Query { } /** - * Adds a ParameterSetter/ + * Adds a parameter to the query using the specified ParameterSetter. * - * @param setter Setter for a parameter. - * @return the Qyery. + * @param setter the ParameterSetter used to configure the parameter + * @return the current Query instance for method chaining */ public Query addParameter(ParameterSetter setter) { parameterSetters.add(setter); @@ -99,7 +149,10 @@ public class Query { } /** - * Adds a result factory by name. + * Sets the factory function used to convert a {@link ResultSet} into an instance of type {@code T}. + * + * @param factory the function responsible for mapping a {@code ResultSet} to an object of type {@code T} + * @return the current {@code Query} instance with the specified factory function set */ public Query factory(final Function factory) { this.factory = factory; @@ -107,7 +160,11 @@ public class Query { } /** - * Executes the query and returns a stream of results. This Stream must be closed so that the underlying ResultSet is closed. + * Creates a {@link Stream} from the result set obtained by executing a prepared statement. + * The result set is wrapped in a {@link TrimmingResultSet} to handle data trimming. + * + * @return a {@link Stream} of type T populated with the query results processed using the specified factory + * @throws SQLException if an SQL error occurs while executing the prepared statement or creating the stream */ private Stream stream() throws SQLException { ResultSet rs = createPreparedStatement().executeQuery(); @@ -116,10 +173,11 @@ public class Query { } /** - * Creates a PreparedStatement and applies all Parameter. + * Creates and returns a PreparedStatement object configured with the query text + * and parameters defined for the current instance. * - * @return the created PreparedStatement - * @throws SQLException thrown if the PreparedStatement could not be created. + * @return a PreparedStatement object initialized with the query and parameter values + * @throws SQLException if a database access error occurs or the PreparedStatement cannot be created */ private PreparedStatement createPreparedStatement() throws SQLException { PreparedStatement ps = connection.prepareStatement(queryText); @@ -130,9 +188,12 @@ public class Query { } /** - * Executes a query wich has no result. + * Executes the SQL statement represented by the PreparedStatement created in + * the method {@code createPreparedStatement()}. This method is used to perform + * database operations such as updates or other actions that do not produce a + * result set. * - * @throws SQLException Thrown when query cannot be executed. + * @throws SQLException if a database access error occurs or the SQL statement is invalid. */ public void execute() throws SQLException { try (PreparedStatement ps = createPreparedStatement()) { @@ -141,17 +202,26 @@ public class Query { } /** - * Streams the results of a ResultSet using a factory that creates instances for each row of the ResultSet + * Converts a {@link ResultSet} into a {@link Stream} of objects created using the provided {@link Function} + * factory. The stream ensures resources such as the {@code ResultSet} and its associated statement are + * closed when the stream is closed. * - * @param rs ResultSet to stream from - * @param factory Factory to create instances of T. - * @return Stream of T instances. + * @param rs the {@link ResultSet} to be transformed into a stream + * @param factory a {@link Function} that maps rows of the {@link ResultSet} to objects of type T + * @return a {@link Stream} of objects of type T created from the {@code ResultSet} rows */ private Stream streamFromResultSet(final ResultSet rs, final Function factory) { Iterator iterator = new Iterator<>() { private boolean hasNextChecked = false; private boolean hasNext; + /** + * Checks if the iteration has more elements. This method verifies if the + * underlying {@link ResultSet} contains another row that has not yet been processed. + * + * @return {@code true} if there are more elements in the {@link ResultSet}, + * otherwise {@code false}. + */ @Override @SneakyThrows public boolean hasNext() { @@ -162,6 +232,14 @@ public class Query { return hasNext; } + /** + * Returns the next element in the iteration. This method applies the provided + * factory function to the current row of the {@link ResultSet} to create an object of type T. + * It throws {@link NoSuchElementException} if there are no more elements to iterate. + * + * @return the next element of type T as created by the factory function from the current row of the {@link ResultSet} + * @throws NoSuchElementException if the iteration has no more elements + */ @Override public T next() { if (!hasNext()) { @@ -187,6 +265,16 @@ public class Query { }); } + /** + * Provides a managed stream to the given handler and ensures proper resource closing after use. + * A {@code Stream} is opened and passed to the specified handler as an argument. + * The stream will be automatically closed when the handler finishes execution or throws an exception. + * + * @param handler a function which receives a {@code Stream} and processes it, returning a result of type {@code R}. + * @param the type of the result produced by the handler. + * @return the result returned by the handler after processing the stream. + * @throws SQLException if an SQL error occurs during the creation or handling of the stream. + */ public R withStream(Function, R> handler) throws SQLException { try (Stream stream = stream()) { return handler.apply(stream); @@ -194,37 +282,44 @@ public class Query { } /** - * Function with three parameters and no result which can throw an SQLException + * Represents a functional interface that accepts three input arguments and allows for operations + * that can throw an {@link SQLException}. This can be useful in scenarios where SQL-related + * logic requires processing with three parameters. * - * @param type of first parameter - * @param type of second parameter - * @param type of third parameter + * @param the type of the first input to the operation + * @param the type of the second input to the operation + * @param the type of the third input to the operation */ @FunctionalInterface public interface TriSqlFunction { /** - * Calls the thre parameter function. + * Executes an operation on three input arguments and allows for the operation to throw + * an {@link SQLException}. This method is intended to facilitate SQL-related processes + * where three parameters are involved. * - * @param t first parameter. - * @param u second parameter. - * @param v third parameter. - * @throws SQLException Function could throw an SQLException. + * @param t the first input argument + * @param u the second input argument + * @param v the third input argument + * @throws SQLException if an SQL error occurs during execution */ void apply(T t, U u, V v) throws SQLException; } /** - * ParameterSetter is a function Interface that could be used to alter a PreparedStatement. + * Functional interface designed to handle operations on a PreparedStatement. + * Represents a single abstract method that performs specific work on the + * provided PreparedStatement instance. */ @FunctionalInterface public interface ParameterSetter { /** - * Does the required work on PreparedStatement. + * Applies an operation to the given PreparedStatement object. + * This method is intended to set parameters or perform other modifications on a PreparedStatement. * - * @param ps PreparedStatement to work on. - * @throws SQLException Could be thrown when working on PreparedStatement. + * @param ps the PreparedStatement instance to be modified or configured + * @throws SQLException if a database access error occurs while applying the operation */ void apply(PreparedStatement ps) throws SQLException; } diff --git a/core/src/main/java/de/neitzel/core/sql/TrimmingResultSet.java b/core/src/main/java/de/neitzel/core/sql/TrimmingResultSet.java index 3acff20..7a0b55a 100644 --- a/core/src/main/java/de/neitzel/core/sql/TrimmingResultSet.java +++ b/core/src/main/java/de/neitzel/core/sql/TrimmingResultSet.java @@ -11,22 +11,34 @@ import java.util.Calendar; import java.util.Map; /** - * ResultSet that trims all String values. + * A wrapper implementation of the {@link ResultSet} interface that modifies or intercepts + * specific behavior, such as trimming data retrieved from the underlying {@code ResultSet}. + * + *

This class delegates method calls to an encapsulated {@link ResultSet} instance. + * If any additional behaviors or transformations are applied, they are documented + * in the respective overridden method descriptions. */ @RequiredArgsConstructor public class TrimmingResultSet implements ResultSet { /** - * The ResultSet used to read data from. + * Represents the result set obtained from executing a database query. + * This object provides functionality to traverse and access the data + * in a tabular format returned by the query execution. + * + * This ResultSet instance is immutable and cannot be modified after initialization. + * It is typically used for reading query results and is tied to a specific + * SQL query execution lifecycle. */ private final ResultSet resultSet; /** - * Gets string. + * Retrieves the string value from the specified column index of the current row in the ResultSet. + * The value is trimmed to remove leading and trailing whitespace. If the value is null, it returns null. * - * @param columnIndex the column index - * @return the string - * @throws SQLException the sql exception + * @param columnIndex the column index, starting from 1, from which the string is to be retrieved + * @return the trimmed string value from the specified column, or null if the column value is SQL NULL + * @throws SQLException if a database access error occurs or the columnIndex is not valid */ @Override public String getString(final int columnIndex) throws SQLException { @@ -35,11 +47,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets string. + * Retrieves the value of the specified column as a trimmed string. * - * @param columnLabel the column label - * @return the string - * @throws SQLException the sql exception + * @param columnLabel the label of the column from which to retrieve the value + * @return the trimmed string value of the specified column, or null if the column value is SQL NULL + * @throws SQLException if a database access error occurs or the columnLabel is invalid */ @Override public String getString(final String columnLabel) throws SQLException { @@ -48,10 +60,10 @@ public class TrimmingResultSet implements ResultSet { } /** - * Next boolean. + * Moves the cursor forward one row from its current position in the ResultSet. * - * @return the boolean - * @throws SQLException the sql exception + * @return true if the new current row is valid, false if there are no more rows + * @throws SQLException if a database access error occurs or this method is called on a closed ResultSet */ @Override public boolean next() throws SQLException { @@ -59,9 +71,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Close. + * Closes the current resource associated with this instance. + * This method ensures that the ResultSet object is properly closed to + * release database and JDBC resources. * - * @throws SQLException the sql exception + * @throws SQLException if a database access error occurs while closing the ResultSet. */ @Override public void close() throws SQLException { @@ -69,10 +83,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Was null boolean. + * Checks if the last column read had a value of SQL NULL. + * This method should be called only after calling a getter method + * on the ResultSet to retrieve a column value. * - * @return the boolean - * @throws SQLException the sql exception + * @return true if the last column read was SQL NULL; false otherwise + * @throws SQLException if a database access error occurs */ @Override public boolean wasNull() throws SQLException { @@ -80,11 +96,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets boolean. + * Retrieves the value of the designated column in the current row of the result set + * as a boolean. * - * @param columnIndex the column index - * @return the boolean - * @throws SQLException the sql exception + * @param columnIndex the index of the column, starting from 1 + * @return the column value as a boolean + * @throws SQLException if a database access error occurs or the columnIndex is out of bounds */ @Override public boolean getBoolean(final int columnIndex) throws SQLException { @@ -92,11 +109,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets boolean. + * Retrieves the value of the designated column as a boolean. * - * @param columnLabel the column label - * @return the boolean - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, + * then the label is the name of the column. + * @return the column value as a boolean. Returns false if the value in the designated column is SQL NULL. + * @throws SQLException if a database access error occurs or the column label is not valid. */ @Override public boolean getBoolean(final String columnLabel) throws SQLException { @@ -104,11 +122,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets byte. + * Retrieves the value of the designated column in the current row + * of this ResultSet object as a byte. * - * @param columnIndex the column index - * @return the byte - * @throws SQLException the sql exception + * @param columnIndex the first column is 1, the second is 2, and so on; + * must be a valid column index + * @return the column value as a byte + * @throws SQLException if the column index is invalid or if a database access error occurs */ @Override public byte getByte(final int columnIndex) throws SQLException { @@ -116,11 +136,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets byte. + * Retrieves the value of the designated column in the current row of this ResultSet + * object as a byte. * - * @param columnLabel the column label - * @return the byte - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with the SQL AS clause. + * If the SQL AS clause was not specified, then the label is + * the name of the column. + * @return the column value as a byte. If the value is SQL NULL, the result is 0. + * @throws SQLException if the columnLabel is not valid or a database access error occurs. */ @Override public byte getByte(final String columnLabel) throws SQLException { @@ -128,11 +151,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets short. + * Retrieves the value of the designated column in the current row of this ResultSet object + * as a short. * - * @param columnIndex the column index - * @return the short - * @throws SQLException the sql exception + * @param columnIndex the column index, starting from 1, which indicates the column to retrieve + * the short value from + * @return the column value as a short + * @throws SQLException if a database access error occurs or the column index is invalid */ @Override public short getShort(final int columnIndex) throws SQLException { @@ -140,11 +165,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets short. + * Retrieves the value of the specified column as a short. * - * @param columnLabel the column label - * @return the short - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with the SQL query + * @return the column value as a short + * @throws SQLException if a database access error occurs or the columnLabel is not valid */ @Override public short getShort(final String columnLabel) throws SQLException { @@ -152,11 +177,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets int. + * Retrieves the value of the column specified by the given index as an int. * - * @param columnIndex the column index - * @return the int - * @throws SQLException the sql exception + * @param columnIndex the index of the column in the current row, starting from 1 + * @return the column value as an int + * @throws SQLException if a database access error occurs or the column index is invalid */ @Override public int getInt(final int columnIndex) throws SQLException { @@ -164,11 +189,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets int. + * Retrieves the value of the column designated by the given label as an int. * - * @param columnLabel the column label - * @return the int - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with the SQL AS clause, or the original column name + * @return the column value as an int + * @throws SQLException if a database access error occurs or the column label is not valid */ @Override public int getInt(final String columnLabel) throws SQLException { @@ -176,11 +201,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets long. + * Retrieves the value of the designated column in the current row of the ResultSet + * as a long value. * - * @param columnIndex the column index - * @return the long - * @throws SQLException the sql exception + * @param columnIndex the index of the column from which to retrieve the value, starting from 1 + * @return the long value of the designated column + * @throws SQLException if a database access error occurs or the column index is invalid */ @Override public long getLong(final int columnIndex) throws SQLException { @@ -188,11 +214,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets long. + * Retrieves the value of the specified column as a long. * - * @param columnLabel the column label - * @return the long - * @throws SQLException the sql exception + * @param columnLabel the name of the column from which to retrieve the value + * @return the long value of the specified column + * @throws SQLException if a database access error occurs or the column label is not valid */ @Override public long getLong(final String columnLabel) throws SQLException { @@ -200,11 +226,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets float. + * Retrieves the value of the designated column in the current row of this + * ResultSet as a float. * - * @param columnIndex the column index - * @return the float - * @throws SQLException the sql exception + * @param columnIndex the index of the column, starting from 1, from which + * the float value is to be retrieved + * @return the column value as a float + * @throws SQLException if a database access error occurs or the column + * index is invalid */ @Override public float getFloat(final int columnIndex) throws SQLException { @@ -212,11 +241,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets float. + * Retrieves the value of the specified column as a float from the result set. * - * @param columnLabel the column label - * @return the float - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified in the SQL query + * @return the column value as a float + * @throws SQLException if a database access error occurs or the columnLabel is not valid */ @Override public float getFloat(final String columnLabel) throws SQLException { @@ -224,11 +253,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets double. + * Retrieves the value of the designated column in the current row of this + * ResultSet object as a double. * - * @param columnIndex the column index - * @return the double - * @throws SQLException the sql exception + * @param columnIndex the index of the column, starting from 1, from which + * the double value is to be retrieved + * @return the column value as a double + * @throws SQLException if a database access error occurs or the column + * index is invalid */ @Override public double getDouble(final int columnIndex) throws SQLException { @@ -236,11 +268,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets double. + * Retrieves the value of the designated column as a double. * - * @param columnLabel the column label - * @return the double - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified in the SQL query + * @return the column value as a double + * @throws SQLException if a database access error occurs or the columnLabel is not valid */ @Override public double getDouble(final String columnLabel) throws SQLException { @@ -248,12 +280,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets big decimal. + * Retrieves the value of the specified column as a BigDecimal object with the specified scale. * - * @param columnIndex the column index - * @param scale the scale - * @return the big decimal - * @throws SQLException the sql exception + * @param columnIndex the index of the column (1-based) from which to retrieve the BigDecimal value + * @param scale the scale to apply to the retrieved BigDecimal value + * @return the BigDecimal value from the specified column with the given scale + * @throws SQLException if a database access error occurs or the column index is invalid */ @Override @Deprecated @@ -262,11 +294,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets big decimal. + * Retrieves the value of the specified column as a {@code BigDecimal} object. * - * @param columnIndex the column index - * @return the big decimal - * @throws SQLException the sql exception + * @param columnIndex the column index (starting at 1) from which the BigDecimal value is to be retrieved + * @return the column value as a {@code BigDecimal}, or null if the column value is SQL NULL + * @throws SQLException if a database access error occurs or the column index is invalid */ @Override public BigDecimal getBigDecimal(final int columnIndex) throws SQLException { @@ -274,12 +306,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets big decimal. + * Retrieves the value of the designated column as a {@code BigDecimal} with the specified scale. * - * @param columnLabel the column label - * @param scale the scale - * @return the big decimal - * @throws SQLException the sql exception + * @param columnLabel the label for the column in the SQL result set + * @param scale the number of digits to the right of the decimal point + * @return the value of the column as a {@code BigDecimal} with the specified scale + * @throws SQLException if a database access error occurs or this method is called on a closed result set */ @Override @Deprecated @@ -288,11 +320,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets big decimal. + * Retrieves the value of the specified column as a {@code BigDecimal} object. * - * @param columnLabel the column label - * @return the big decimal - * @throws SQLException the sql exception + * @param columnLabel the label of the column from which to retrieve the value + * @return the column value as a {@code BigDecimal} object, or {@code null} if the value is SQL {@code NULL} + * @throws SQLException if an SQL error occurs while retrieving the value */ @Override public BigDecimal getBigDecimal(final String columnLabel) throws SQLException { @@ -300,11 +332,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Get bytes byte [ ]. + * Retrieves the value of the designated column in the current row of this ResultSet + * object as a byte array. * - * @param columnIndex the column index - * @return the byte [ ] - * @throws SQLException the sql exception + * @param columnIndex the first column is 1, the second is 2, and so on; indicates + * which column value to retrieve. + * @return the column value as a byte array. Returns null if the SQL value is + * SQL NULL. + * @throws SQLException if the columnIndex is invalid or a database access error occurs. */ @Override public byte[] getBytes(final int columnIndex) throws SQLException { @@ -312,11 +347,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Get bytes byte [ ]. + * Retrieves the value of the specified column in the current row of this ResultSet + * as a byte array. The column is specified using the column label. * - * @param columnLabel the column label - * @return the byte [ ] - * @throws SQLException the sql exception + * @param columnLabel the label for the column from which to retrieve the value + * @return a byte array containing the column value; null if the value is SQL NULL + * @throws SQLException if a database access error occurs or the column label is invalid */ @Override public byte[] getBytes(final String columnLabel) throws SQLException { @@ -324,11 +360,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets date. + * Retrieves the value of the designated column in the current row of this result set + * as a {@code Date} object. * - * @param columnIndex the column index - * @return the date - * @throws SQLException the sql exception + * @param columnIndex the first column is 1, the second column is 2, and so on + * @return the {@code Date} value of the specified column in the current row + * @throws SQLException if a database access error occurs or the column index is invalid */ @Override public Date getDate(final int columnIndex) throws SQLException { @@ -336,11 +373,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets date. + * Retrieves the date value of the specified column. * - * @param columnLabel the column label - * @return the date - * @throws SQLException the sql exception + * @param columnLabel the label of the column from which the date value is to be retrieved + * @return the date value of the specified column, or null if the value is SQL NULL + * @throws SQLException if a database access error occurs or the column label is invalid */ @Override public Date getDate(final String columnLabel) throws SQLException { @@ -348,12 +385,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets date. + * Retrieves the value of the designated column as a Date object + * using the given Calendar object for interpreting the timezone. * - * @param columnIndex the column index - * @param cal the cal - * @return the date - * @throws SQLException the sql exception + * @param columnIndex the index of the column, starting from 1 + * @param cal the Calendar object to use for interpreting dates, or null + * @return the value of the column as a Date object; + * if the value is SQL NULL, the result is null + * @throws SQLException if a database access error occurs or the column index is invalid */ @Override public Date getDate(final int columnIndex, final Calendar cal) throws SQLException { @@ -361,12 +400,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets date. + * Retrieves the value of the specified column as a Date object using the given Calendar instance to construct the date. * - * @param columnLabel the column label - * @param cal the cal - * @return the date - * @throws SQLException the sql exception + * @param columnLabel the label for the column from which to retrieve the value + * @param cal the Calendar instance to use for determining the date + * @return the column value as a Date object; if the value is SQL NULL, the result is null + * @throws SQLException if a database access error occurs or the column label is invalid */ @Override public Date getDate(final String columnLabel, final Calendar cal) throws SQLException { @@ -374,11 +413,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets time. + * Retrieves the value of the designated column as a {@code Time} object. * - * @param columnIndex the column index - * @return the time - * @throws SQLException the sql exception + * @param columnIndex the index of the column, starting from 1 + * @return the {@code Time} value of the specified column in the current row + * @throws SQLException if the column index is invalid or a database access error occurs */ @Override public Time getTime(final int columnIndex) throws SQLException { @@ -386,11 +425,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets time. + * Retrieves the value of the specified column as a {@code Time} object. * - * @param columnLabel the column label - * @return the time - * @throws SQLException the sql exception + * @param columnLabel the label of the column from which to retrieve the value + * @return a {@code Time} object representing the value of the specified column + * @throws SQLException if a database access error occurs or the columnLabel is not valid */ @Override public Time getTime(final String columnLabel) throws SQLException { @@ -398,12 +437,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets time. + * Retrieves the value of the designated column as a {@code Time} object. * - * @param columnIndex the column index - * @param cal the cal - * @return the time - * @throws SQLException the sql exception + * @param columnIndex an integer indicating the column index, starting at 1 + * @param cal the {@code Calendar} object to use for constructing the {@code Time} object + * @return the column value as a {@code Time} object or null if the column value is SQL {@code NULL} + * @throws SQLException if a database access error occurs, the column index is invalid, + * or the {@code Calendar} object is null */ @Override public Time getTime(final int columnIndex, final Calendar cal) throws SQLException { @@ -411,12 +451,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets time. + * Retrieves the value of the specified column as a {@link Time} object using the given calendar for timezone adjustments. * - * @param columnLabel the column label - * @param cal the cal - * @return the time - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with the SQL query + * @param cal the {@link Calendar} object to use in constructing the date + * @return the column value as a {@link Time} object; if the value is SQL {@code NULL}, the result is {@code null} + * @throws SQLException if a database access error occurs or the column label is not valid */ @Override public Time getTime(final String columnLabel, final Calendar cal) throws SQLException { @@ -424,11 +464,15 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets timestamp. + * Retrieves the value of the designated column in the current row of this + * ResultSet object as a Timestamp object. * - * @param columnIndex the column index - * @return the timestamp - * @throws SQLException the sql exception + * @param columnIndex the column index, starting at 1, from which the timestamp + * value is to be retrieved + * @return a Timestamp object representing the SQL TIMESTAMP value in the specified + * column of the current row + * @throws SQLException if a database access error occurs, the column index is invalid, + * or the data in the column is not a valid timestamp */ @Override public Timestamp getTimestamp(final int columnIndex) throws SQLException { @@ -436,11 +480,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets timestamp. + * Retrieves the timestamp value for the specified column label from the underlying result set. * - * @param columnLabel the column label - * @return the timestamp - * @throws SQLException the sql exception + * @param columnLabel the label for the column from which to retrieve the timestamp + * @return the timestamp value of the specified column; may return null if the value is SQL NULL + * @throws SQLException if a database access error occurs or if the column label is invalid */ @Override public Timestamp getTimestamp(final String columnLabel) throws SQLException { @@ -448,12 +492,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets timestamp. + * Retrieves the value of the specified column as a {@code Timestamp} object, + * using the provided {@code Calendar} to construct the {@code Timestamp}. * - * @param columnIndex the column index - * @param cal the cal - * @return the timestamp - * @throws SQLException the sql exception + * @param columnIndex the index of the column (1-based) whose value is to be retrieved + * @param cal the {@code Calendar} object to use for interpreting the timestamp + * @return the column value as a {@code Timestamp} object; returns {@code null} if the column value is SQL {@code NULL} + * @throws SQLException if the column index is invalid or a database access error occurs */ @Override public Timestamp getTimestamp(final int columnIndex, final Calendar cal) throws SQLException { @@ -461,12 +506,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets timestamp. + * Retrieves the value of the designated column as a {@code Timestamp} object in the specified calendar. + * This method uses the provided {@code Calendar} to construct the {@code Timestamp} object. * - * @param columnLabel the column label - * @param cal the cal - * @return the timestamp - * @throws SQLException the sql exception + * @param columnLabel the label for the column from which to retrieve the value + * @param cal the {@code Calendar} object to use to construct the timestamp + * @return the column value as a {@code Timestamp}; if the value is SQL {@code NULL}, the value returned is {@code null} + * @throws SQLException if a database access error occurs or the column label is invalid */ @Override public Timestamp getTimestamp(final String columnLabel, final Calendar cal) throws SQLException { @@ -474,11 +520,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets ascii stream. + * Retrieves the value of the designated column in the current row of this ResultSet object as a stream of ASCII characters. * - * @param columnIndex the column index - * @return the ascii stream - * @throws SQLException the sql exception + * @param columnIndex the column index, starting from 1, indicating which column's value to retrieve + * @return an InputStream object that contains the ASCII data of the specified column + * @throws SQLException if a database access error occurs or the columnIndex is invalid */ @Override public InputStream getAsciiStream(final int columnIndex) throws SQLException { @@ -486,11 +532,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets unicode stream. + * Retrieves the value of the designated column in the current row as a stream of Unicode characters. + * The stream is read in the Java Unicode character format. + * This method is used to access database data as Unicode text. * - * @param columnIndex the column index - * @return the unicode stream - * @throws SQLException the sql exception + * @param columnIndex the index of the column in the result set, starting from 1 for the first column + * @return an InputStream object that provides a stream of Unicode characters, + * or null if the SQL value is null + * @throws SQLException if a database access error occurs or the column index is invalid */ @Override public InputStream getUnicodeStream(final int columnIndex) throws SQLException { @@ -498,11 +547,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets ascii stream. + * Retrieves the value of the specified column as a stream of ASCII characters. * - * @param columnLabel the column label - * @return the ascii stream - * @throws SQLException the sql exception + * @param columnLabel the label for the column from which the stream will be retrieved + * @return an InputStream object containing the ASCII stream of the designated column value + * @throws SQLException if a database access error occurs or the columnLabel is not valid */ @Override public InputStream getAsciiStream(final String columnLabel) throws SQLException { @@ -510,11 +559,16 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets unicode stream. + * Retrieves the value of the designated column labeled by the given column label + * as a Unicode stream. The data will be returned as a stream of Unicode characters. + * This method is intended for reading long text values or other binary data + * that can be represented as Unicode. * - * @param columnLabel the column label - * @return the unicode stream - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified in the SQL query + * @return an InputStream containing the Unicode stream of the designated column, + * or null if the value is SQL NULL + * @throws SQLException if a database access error occurs or if the columnLabel + * does not match an existing column */ @Override public InputStream getUnicodeStream(final String columnLabel) throws SQLException { @@ -522,23 +576,20 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets binary stream. - * - * @param columnIndex the column index - * @return the binary stream - * @throws SQLException the sql exception - */ + * Retrieves the value of the designated*/ @Override public InputStream getBinaryStream(final int columnIndex) throws SQLException { return resultSet.getBinaryStream(columnIndex); } /** - * Gets binary stream. + * Retrieves the value of the designated column as a binary input stream. * - * @param columnLabel the column label - * @return the binary stream - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified in the SQL query + * @return an InputStream object that contains the binary data of the designated column + * @throws SQLException if the columnLabel is not valid; + * if a database access error occurs; + * or if this method is called on a closed result set */ @Override public InputStream getBinaryStream(final String columnLabel) throws SQLException { @@ -546,10 +597,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets warnings. + * Retrieves the first warning reported by calls on the underlying object. + * Subsequent warnings on the object are chained to the first SQLWarning object. * - * @return the warnings - * @throws SQLException the sql exception + * @return the first SQLWarning object or null if there are no warnings + * @throws SQLException if a database access error occurs */ @Override public SQLWarning getWarnings() throws SQLException { @@ -557,11 +609,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets character stream. + * Retrieves the value of the designated column in the current row of + * this ResultSet object as a java.io.Reader object. * - * @param columnIndex the column index - * @return the character stream - * @throws SQLException the sql exception + * @param columnIndex the column index (1-based) for which the character stream is to be retrieved + * @return a Reader object that contains the data of the specified column; if the value is SQL NULL, this method returns null + * @throws SQLException if a database access error occurs or this method is called on a closed result set */ @Override public Reader getCharacterStream(final int columnIndex) throws SQLException { @@ -569,11 +622,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets character stream. + * Retrieves the character stream for the value of the specified column label in the current row of this ResultSet. + * This allows reading character data from the column as a Reader. * - * @param columnLabel the column label - * @return the character stream - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified in the ResultSet object, which is typically the SQL AS name if available, or the actual column name. + * @return a Reader object containing the column value as a stream of characters; null if the value is SQL NULL. + * @throws SQLException if a database access error occurs or the columnLabel is not valid. */ @Override public Reader getCharacterStream(final String columnLabel) throws SQLException { @@ -581,11 +635,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets n string. + * Retrieves the NString value at the specified column index from the underlying result set. + * If the value is not null, it trims any leading or trailing whitespace characters. * - * @param columnIndex the column index - * @return the n string - * @throws SQLException the sql exception + * @param columnIndex the index of the column from which to retrieve the NString value, starting from 1 + * @return the trimmed NString value at the specified column index, or null if the value is null + * @throws SQLException if a database access error occurs or the column index is invalid */ @Override public String getNString(final int columnIndex) throws SQLException { @@ -594,11 +649,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets n string. + * Retrieves the value of the designated column as a string in the current row of the result set. + * The string is processed to ensure leading and trailing whitespace is removed. * - * @param columnLabel the column label - * @return the n string - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified in the query + * @return the column value as a trimmed string, or null if the value is SQL NULL + * @throws SQLException if the columnLabel is not valid, if there is a database access error, or other SQL issues occur */ @Override public String getNString(final String columnLabel) throws SQLException { @@ -607,11 +663,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets n character stream. + * Retrieves the value of the designated column in the current row of + * this ResultSet object as a Reader object. The column value is expected + * to be a national character stream in the Java programming language. * - * @param columnIndex the column index - * @return the n character stream - * @throws SQLException the sql exception + * @param columnIndex the column index (1-based) of the desired column in this ResultSet + * @return a Reader object that contains the column value; if the value is SQL NULL, then null is returned + * @throws SQLException if the columnIndex is invalid or a database access error occurs */ @Override public Reader getNCharacterStream(final int columnIndex) throws SQLException { @@ -619,11 +677,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets n character stream. + * Retrieves the value of the designated column in the current row of this ResultSet + * object as a character stream in the form of a Reader. * - * @param columnLabel the column label - * @return the n character stream - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified in the SQL query + * @return a Reader object that contains the column value; if the column value is SQL NULL, the value returned is null + * @throws SQLException if the columnLabel is not valid, the result set is closed, or a database access error occurs */ @Override public Reader getNCharacterStream(final String columnLabel) throws SQLException { @@ -631,9 +690,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Clear warnings. + * Clears all warnings reported on this ResultSet object. * - * @throws SQLException the sql exception + * This method delegates the call to the underlying ResultSet's clearWarnings method, + * ensuring that any chain of warnings previously recorded is cleared. + * + * @throws SQLException if a database access error occurs or this method + * is called on a closed ResultSet. */ @Override public void clearWarnings() throws SQLException { @@ -641,10 +704,10 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets cursor name. + * Retrieves the name of the SQL cursor used by this ResultSet object, if available. * - * @return the cursor name - * @throws SQLException the sql exception + * @return the name of the SQL cursor, or null if the cursor does not have a name. + * @throws SQLException if a database access error occurs or this method is called on a closed result set. */ @Override public String getCursorName() throws SQLException { @@ -652,10 +715,10 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets meta data. + * Retrieves the metadata for the result set. * - * @return the meta data - * @throws SQLException the sql exception + * @return a ResultSetMetaData object that contains information about the columns of the result set. + * @throws SQLException if a database access error occurs. */ @Override public ResultSetMetaData getMetaData() throws SQLException { @@ -663,11 +726,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets object. + * Retrieves the value of the designated column in the current row of this ResultSet object + * as an Object. The type of the object returned is determined by the SQL type of the column. * - * @param columnIndex the column index - * @return the object - * @throws SQLException the sql exception + * @param columnIndex the index of the column to retrieve, where the first column is 1 + * @return the value of the designated column as an Object; returns null if the value is SQL NULL + * @throws SQLException if a database access error occurs or the column index is out of bounds */ @Override public Object getObject(final int columnIndex) throws SQLException { @@ -675,11 +739,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets object. + * Retrieves the value of the designated column in the current row of this ResultSet object + * as an Object. * - * @param columnLabel the column label - * @return the object - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with the SQL AS clause. + * If the SQL AS clause was not specified, the label is the name of the column. + * @return the value of the specified column as an Object + * @throws SQLException if a database access error occurs or this method is called on a closed ResultSet */ @Override public Object getObject(final String columnLabel) throws SQLException { @@ -687,12 +753,19 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets object. + * Retrieves the value of the designated column in the current row of this ResultSet object + * as an Object in the Java programming language. The value will be converted to the specified + * Java class using the provided type map. * - * @param columnIndex the column index - * @param map the map - * @return the object - * @throws SQLException the sql exception + * @param columnIndex the first column is 1, the second is 2, and so on; must be in the range + * [1, number of columns in the current row]. + * @param map a mapping of SQL structured types or SQL DISTINCT types to classes in the Java + * programming language. The type map parameter overrides the default type map + * associated with the connection for this call only. + * @return an Object that represents the SQL value in the specified column, converted to a + * Java object using the provided type map. Returns null if the SQL value is SQL NULL. + * @throws SQLException if a database access error occurs, the columnIndex is out of bounds, + * or if the type map is invalid. */ @Override public Object getObject(final int columnIndex, final Map> map) throws SQLException { @@ -700,11 +773,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets ref. + * Retrieves the value of the specified column as a {@link Ref} object. * - * @param columnIndex the column index - * @return the ref - * @throws SQLException the sql exception + * @param columnIndex the 1-based index of the column from which the value is to be retrieved + * @return the value of the specified column as a {@link Ref} object, or null if the value is SQL NULL + * @throws SQLException if a database access error occurs or the column index is invalid */ @Override public Ref getRef(final int columnIndex) throws SQLException { @@ -712,11 +785,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets blob. + * Retrieves the Blob object designated by the given column index from the current row of the result set. * - * @param columnIndex the column index - * @return the blob - * @throws SQLException the sql exception + * @param columnIndex the column index, starting from 1, from which the Blob object is to be retrieved. + * @return the Blob object at the specified column index; may be null if the SQL value is SQL NULL. + * @throws SQLException if a database access error occurs or if this method is called on a closed result set. */ @Override public Blob getBlob(final int columnIndex) throws SQLException { @@ -724,11 +797,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets clob. + * Retrieves the CLOB value at the specified column index from the underlying ResultSet. * - * @param columnIndex the column index - * @return the clob - * @throws SQLException the sql exception + * @param columnIndex the 1-based index of the column from which the CLOB is to be retrieved + * @return the CLOB value from the specified column, or null if the column value is SQL NULL + * @throws SQLException if a database access error occurs or the columnIndex is invalid */ @Override public Clob getClob(final int columnIndex) throws SQLException { @@ -736,11 +809,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets array. + * Retrieves an SQL Array object from the specified column index + * of the current row in the ResultSet. * - * @param columnIndex the column index - * @return the array - * @throws SQLException the sql exception + * @param columnIndex the index of the column to retrieve the Array from, starting from 1 + * @return an Array object representing the SQL Array value at the specified column index + * @throws SQLException if a database access error occurs or the column index is invalid */ @Override public Array getArray(final int columnIndex) throws SQLException { @@ -748,12 +822,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets object. + * Retrieves the value of the specified column as an Object, using the given type map for + * custom mappings of SQL user-defined types to Java classes. * - * @param columnLabel the column label - * @param map the map - * @return the object - * @throws SQLException the sql exception + * @param columnLabel the label for the column from which to retrieve the value + * @param map a map of SQL type names to Java classes for custom type mappings + * @return the value of the specified column as an Object, or null if the value is SQL NULL + * @throws SQLException if a database access error occurs, the columnLabel is not valid, + * or a mapping for a user-defined type is invalid */ @Override public Object getObject(final String columnLabel, final Map> map) throws SQLException { @@ -761,11 +837,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets ref. + * Retrieves the value of the designated column as a Ref object. * - * @param columnLabel the column label - * @return the ref - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with the SQL AS clause. + * If the SQL AS clause was not specified, then the label is the name of the column. + * @return a Ref object representing the SQL REF value in the specified column. + * @throws SQLException if a database access error occurs or this method + * is called on a closed result set. */ @Override public Ref getRef(final String columnLabel) throws SQLException { @@ -773,11 +851,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets blob. + * Retrieves the value of the designated column as a {@code Blob} object. * - * @param columnLabel the column label - * @return the blob - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified, which is the name of the column as defined in the database + * @return the {@code Blob} object representing the value of the specified column + * @throws SQLException if a database access error occurs or the column label is not valid */ @Override public Blob getBlob(final String columnLabel) throws SQLException { @@ -785,11 +863,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets clob. + * Retrieves the CLOB (Character Large Object) value of the designated column + * as specified by the column label. * - * @param columnLabel the column label - * @return the clob - * @throws SQLException the sql exception + * @param columnLabel the label for the column from which to retrieve the CLOB value + * @return the CLOB object containing the value of the designated column + * @throws SQLException if a database access error occurs or the columnLabel is invalid */ @Override public Clob getClob(final String columnLabel) throws SQLException { @@ -797,11 +876,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets array. + * Retrieves the SQL {@code Array} object designated by the specified column label. * - * @param columnLabel the column label - * @return the array - * @throws SQLException the sql exception + * @param columnLabel the label for the column from which to retrieve the SQL {@code Array} + * @return the SQL {@code Array} object for the specified column label, or {@code null} if the SQL value is {@code NULL} + * @throws SQLException if the column label is not valid or a database access error occurs */ @Override public Array getArray(final String columnLabel) throws SQLException { @@ -809,11 +888,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Find column int. + * Retrieves the column index for the specified column label in the result set. * - * @param columnLabel the column label - * @return the int - * @throws SQLException the sql exception + * @param columnLabel the label of the column for which the index is to be retrieved + * @return the column index corresponding to the specified label + * @throws SQLException if the column label is not valid or a database access error occurs */ @Override public int findColumn(final String columnLabel) throws SQLException { @@ -821,10 +900,10 @@ public class TrimmingResultSet implements ResultSet { } /** - * Is before first boolean. + * Checks if the cursor is positioned before the first row in the result set. * - * @return the boolean - * @throws SQLException the sql exception + * @return true if the cursor is before the first row; false otherwise + * @throws SQLException if a database access error occurs or this method is called on a closed result set */ @Override public boolean isBeforeFirst() throws SQLException { @@ -832,10 +911,10 @@ public class TrimmingResultSet implements ResultSet { } /** - * Is after last boolean. + * Checks if the cursor is positioned after the last row in the ResultSet. * - * @return the boolean - * @throws SQLException the sql exception + * @return true if the cursor is after the last row; false otherwise. + * @throws SQLException if a database access error occurs or this method is called on a closed ResultSet. */ @Override public boolean isAfterLast() throws SQLException { @@ -843,10 +922,10 @@ public class TrimmingResultSet implements ResultSet { } /** - * Is first boolean. + * Checks if the cursor is positioned on the first row of the ResultSet. * - * @return the boolean - * @throws SQLException the sql exception + * @return true if the cursor is on the first row; false otherwise + * @throws SQLException if a database access error occurs or the result set is closed */ @Override public boolean isFirst() throws SQLException { @@ -854,10 +933,10 @@ public class TrimmingResultSet implements ResultSet { } /** - * Is last boolean. + * Checks if the current row of the ResultSet object is the last row. * - * @return the boolean - * @throws SQLException the sql exception + * @return true if the current row is the last row; false otherwise + * @throws SQLException if a database access error occurs or this method is called on a closed ResultSet */ @Override public boolean isLast() throws SQLException { @@ -865,9 +944,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Before first. + * Moves the cursor of the underlying ResultSet to the position + * before the first row. This is typically used to start iterating + * through the rows of the ResultSet from the beginning. * - * @throws SQLException the sql exception + * @throws SQLException if a database access error occurs, + * this method is called on a closed ResultSet, + * or the ResultSet type does not support this operation. */ @Override public void beforeFirst() throws SQLException { @@ -875,9 +958,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * After last. + * Moves the cursor to the end of the ResultSet, just after the last row. + * This method is typically used to iterate backward through the ResultSet. * - * @throws SQLException the sql exception + * @throws SQLException if a database access error occurs or the ResultSet + * is closed. */ @Override public void afterLast() throws SQLException { @@ -885,10 +970,10 @@ public class TrimmingResultSet implements ResultSet { } /** - * First boolean. + * Moves the cursor to the first row of this ResultSet object. * - * @return the boolean - * @throws SQLException the sql exception + * @return true if the cursor is on a valid row; false if there are no rows in the ResultSet. + * @throws SQLException if a database access error occurs or this method is called on a closed ResultSet. */ @Override public boolean first() throws SQLException { @@ -896,10 +981,10 @@ public class TrimmingResultSet implements ResultSet { } /** - * Last boolean. + * Moves the cursor to the last row in the result set. * - * @return the boolean - * @throws SQLException the sql exception + * @return true if the cursor is moved to a valid row; false if there are no rows in the result set. + * @throws SQLException if a database access error occurs or the result set type does not support this operation. */ @Override public boolean last() throws SQLException { @@ -907,10 +992,10 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets row. + * Retrieves the current row number from the underlying ResultSet object. * - * @return the row - * @throws SQLException the sql exception + * @return the current row number, or 0 if there is no current row + * @throws SQLException if a database access error occurs or this method is called on a closed result set */ @Override public int getRow() throws SQLException { @@ -918,11 +1003,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Absolute boolean. + * Moves the cursor to the given row number in this result set. * - * @param row the row - * @return the boolean - * @throws SQLException the sql exception + * @param row the row number to move the cursor to. A positive number moves the cursor + * to the given row number with respect to the beginning, while a negative + * number moves the cursor with respect to the end. + * @return true if the cursor is on a valid row after the move; false if the cursor + * is positioned before the first row or after the last row. + * @throws SQLException if a database access error occurs or the result set is closed. */ @Override public boolean absolute(final int row) throws SQLException { @@ -930,11 +1018,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Relative boolean. + * Moves the cursor a relative number of rows, either forward or backward, from its current position. + * Positive values move the cursor forward, and negative values move it backward. * - * @param rows the rows - * @return the boolean - * @throws SQLException the sql exception + * @param rows the number of rows to move the cursor relative to its current position + * @return {@code true} if the cursor is on a valid row after the move; {@code false} if the cursor is positioned before the first row or after the last row + * @throws SQLException if a database access error occurs or the result set is closed */ @Override public boolean relative(final int rows) throws SQLException { @@ -942,10 +1031,10 @@ public class TrimmingResultSet implements ResultSet { } /** - * Previous boolean. + * Moves the cursor to the previous row in the result set. * - * @return the boolean - * @throws SQLException the sql exception + * @return true if the cursor is moved to a valid row; false if there are no more rows. + * @throws SQLException if a database access error occurs or the result set is closed. */ @Override public boolean previous() throws SQLException { @@ -953,10 +1042,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets fetch direction. + * Retrieves the current fetch direction for the underlying ResultSet. * - * @return the fetch direction - * @throws SQLException the sql exception + * @return the current fetch direction; this will be one of ResultSet.FETCH_FORWARD, + * ResultSet.FETCH_REVERSE, or ResultSet.FETCH_UNKNOWN. + * @throws SQLException if a database access error occurs or if the ResultSet is closed. */ @Override public int getFetchDirection() throws SQLException { @@ -964,10 +1054,15 @@ public class TrimmingResultSet implements ResultSet { } /** - * Sets fetch direction. + * Sets the fetch direction for the ResultSet object to the given direction value. + * The fetch direction gives a hint to the driver about the direction in which + * the rows in the ResultSet will be processed. * - * @param direction the direction - * @throws SQLException the sql exception + * @param direction an integer value indicating the fetch direction. + * The allowed values are ResultSet.FETCH_FORWARD, + * ResultSet.FETCH_REVERSE, or ResultSet.FETCH_UNKNOWN. + * @throws SQLException if a database access error occurs or the given + * fetch direction is not supported. */ @Override public void setFetchDirection(final int direction) throws SQLException { @@ -975,10 +1070,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets fetch size. + * Retrieves the fetch size for the ResultSet associated with this method. + * The fetch size determines how many rows the database fetches at a time from + * the database server when more rows are needed for processing. * - * @return the fetch size - * @throws SQLException the sql exception + * @return the fetch size for the ResultSet + * @throws SQLException if a database access error occurs */ @Override public int getFetchSize() throws SQLException { @@ -986,10 +1083,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Sets fetch size. + * Sets the number of rows that should be fetched from the database when more rows are needed. + * This can improve performance by reducing the number of database fetch operations. * - * @param rows the rows - * @throws SQLException the sql exception + * @param rows the number of rows to fetch. + * @throws SQLException if a database access error occurs or the parameter value is invalid. */ @Override public void setFetchSize(final int rows) throws SQLException { @@ -997,21 +1095,20 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets type. + * Retrieves the type of the underlying `ResultSet` object. * - * @return the type - * @throws SQLException the sql exception - */ + * @return an integer representing the `ResultSet` type. + * @throws SQLException if a database*/ @Override public int getType() throws SQLException { return resultSet.getType(); } /** - * Gets concurrency. + * Retrieves the concurrency mode of the result set. * - * @return the concurrency - * @throws SQLException the sql exception + * @return an integer representing the concurrency mode of the result set. + * @throws SQLException if a database access error occurs or the result set is closed. */ @Override public int getConcurrency() throws SQLException { @@ -1019,10 +1116,10 @@ public class TrimmingResultSet implements ResultSet { } /** - * Row updated boolean. + * Checks if the current row of the result set has been updated. * - * @return the boolean - * @throws SQLException the sql exception + * @return true if the current row has been updated and the result set type is a type that detects changes; false otherwise + * @throws SQLException if a database access error occurs or the method is called on a closed result set */ @Override public boolean rowUpdated() throws SQLException { @@ -1030,10 +1127,10 @@ public class TrimmingResultSet implements ResultSet { } /** - * Row inserted boolean. + * Checks whether the current row in the ResultSet was successfully inserted. * - * @return the boolean - * @throws SQLException the sql exception + * @return true if the current row was inserted, false otherwise + * @throws SQLException if a database access error occurs */ @Override public boolean rowInserted() throws SQLException { @@ -1041,10 +1138,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Row deleted boolean. + * Checks whether the current row in the ResultSet has been deleted. * - * @return the boolean - * @throws SQLException the sql exception + * This method provides a way to determine if the current row, positioned + * in the ResultSet, has been deleted from the database. It relies on the + * underlying ResultSet's implementation of the rowDeleted method. + * + * @return true if the current row has been deleted and false otherwise + * @throws SQLException if a database access error occurs */ @Override public boolean rowDeleted() throws SQLException { @@ -1052,10 +1153,10 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update null. + * Updates the designated column with a SQL NULL value. * - * @param columnIndex the column index - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update. The first column is 1, the second is 2, and so on. + * @throws SQLException if a database access error occurs or if the columnIndex is invalid. */ @Override public void updateNull(final int columnIndex) throws SQLException { @@ -1063,11 +1164,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update boolean. + * Updates the designated column with a boolean value. The update is applied + * to the ResultSet object and can be persisted into the underlying database + * by calling the updateRow method. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the one-based index of the column to update + * @param x the new boolean value to set in the specified column + * @throws SQLException if the column index is invalid, the ResultSet is closed, + * or a database access error occurs */ @Override public void updateBoolean(final int columnIndex, final boolean x) throws SQLException { @@ -1075,11 +1179,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update byte. + * Updates the designated column with a new byte value. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the index of the column, starting from 1, where the byte value will be updated + * @param x the new byte value to set in the specified column + * @throws SQLException if a database access error occurs or if this method is called on a closed result set */ @Override public void updateByte(final int columnIndex, final byte x) throws SQLException { @@ -1087,11 +1191,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update short. + * Updates the designated column with a short value. + * The update is made to the current row of the ResultSet object. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update, where the first column is 1 + * @param x the new column value as a short + * @throws SQLException if a database access error occurs, the ResultSet is in read-only mode, + * or the columnIndex is not valid */ @Override public void updateShort(final int columnIndex, final short x) throws SQLException { @@ -1099,11 +1205,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update int. + * Updates the designated column with an int value. The updater methods are used to update column + * values in the current row or the insert row. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the column index (1-based) of the column to update + * @param x the new column value + * @throws SQLException if a database access error occurs or the columnIndex is invalid */ @Override public void updateInt(final int columnIndex, final int x) throws SQLException { @@ -1111,11 +1218,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update long. + * Updates the designated column with a long value. + * The updater methods are used to update column values in the current row or the insert row. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update, starting from 1 + * @param x the new long value to be set in the column + * @throws SQLException if a database access error occurs or if the result set is read-only */ @Override public void updateLong(final int columnIndex, final long x) throws SQLException { @@ -1123,11 +1231,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update float. + * Updates the designated column with a float value. + * The updater methods are used to update column values in the current row or the insert row. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update, starting from 1 + * @param x the new column value as a float + * @throws SQLException if a database access error occurs or if the method is called on a closed result set */ @Override public void updateFloat(final int columnIndex, final float x) throws SQLException { @@ -1135,11 +1244,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update double. + * Updates the designated column with a double value. The column is specified by its index. + * This method must be called on an updatable ResultSet, and the change is only reflected in + * the ResultSet until updateRow() is called to propagate the change to the underlying database. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the first column is 1, the second is 2, and so on + * @param x the new column value as a double + * @throws SQLException if a database access error occurs or if the column index is not valid */ @Override public void updateDouble(final int columnIndex, final double x) throws SQLException { @@ -1147,11 +1258,15 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update big decimal. + * Updates the designated column with a BigDecimal value. + * The update is made to the current row of the result set. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the first column is 1, the second is 2, and so on. + * @param x the new column value as a BigDecimal. A null value indicates + * SQL NULL. + * @throws SQLException if a database access error occurs, this method is + * called on a closed result set, or the ResultSet is + * in an invalid state. */ @Override public void updateBigDecimal(final int columnIndex, final BigDecimal x) throws SQLException { @@ -1159,11 +1274,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update string. + * Updates the designated column with a provided string value. + * This method must be called on a valid column index within the ResultSet. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update, starting from 1 + * @param x the new string value to set; can be null + * @throws SQLException if a database access error occurs or if the provided index is invalid */ @Override public void updateString(final int columnIndex, final String x) throws SQLException { @@ -1171,11 +1287,15 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update bytes. + * Updates the designated column with a byte array value. The updated value + * will be written to the database when updateRow, insertRow, or deleteRow + * is called. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the first column is 1, the second is 2, and so on + * @param x the new byte array value for the specified column + * @throws SQLException if the columnIndex is invalid; if a database access + * error occurs; if this method is called on a closed result set; + * or if this method is called in a read-only result set */ @Override public void updateBytes(final int columnIndex, final byte[] x) throws SQLException { @@ -1183,11 +1303,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update date. + * Updates the designated column with a Date object. + * The updater methods are used to update column values in the current row or the insert row. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update (1-based) + * @param x the new column value as a Date object + * @throws SQLException if a database access error occurs or if the column index is invalid */ @Override public void updateDate(final int columnIndex, final Date x) throws SQLException { @@ -1195,11 +1316,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update time. + * Updates the designated column with a {@code Time} value. + * The update is made in the current row of the ResultSet. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the first column is 1, the second is 2, and so on + * @param x the new column value; must be a {@code Time} object + * @throws SQLException if the column index is invalid, if a database access error occurs, + * or if the ResultSet is in read-only mode */ @Override public void updateTime(final int columnIndex, final Time x) throws SQLException { @@ -1207,11 +1330,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update timestamp. + * Updates the designated column with a {@link Timestamp} value. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the first column is 1, the second is 2, and so on. + * @param x the new column value; can be null to update the column with SQL NULL. + * @throws SQLException if the column index is invalid, this method is called on a closed result set, + * or a database access error occurs. */ @Override public void updateTimestamp(final int columnIndex, final Timestamp x) throws SQLException { @@ -1219,12 +1343,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update ascii stream. + * Updates the designated column with an ASCII stream value. + * The data in the stream can be read and is then written to the database. * - * @param columnIndex the column index - * @param x the x - * @param length the length - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update, starting from 1 + * @param x the input stream containing the ASCII data to set + * @param length the number of bytes in the input stream to write to the column + * @throws SQLException if a database access error occurs or the column index is invalid */ @Override public void updateAsciiStream(final int columnIndex, final InputStream x, final int length) throws SQLException { @@ -1232,12 +1357,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update binary stream. + * Updates the designated column with a binary stream value. * - * @param columnIndex the column index - * @param x the x - * @param length the length - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update, where the first column is 1 + * @param x the InputStream containing the binary data to set in the column + * @param length the number of bytes in the InputStream to read and write to the column + * @throws SQLException if a database access error occurs or the columnIndex is invalid */ @Override public void updateBinaryStream(final int columnIndex, final InputStream x, final int length) throws SQLException { @@ -1245,12 +1370,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update character stream. + * Updates the designated column with a character stream value. The data will be read from + * the provided Reader object and written to the database. The number of characters to be written + * is specified by the length parameter. * - * @param columnIndex the column index - * @param x the x - * @param length the length - * @throws SQLException the sql exception + * @param columnIndex the index of the column to be updated, starting from 1 + * @param x the Reader object containing the character data to be written + * @param length the number of characters to be written from the Reader + * @throws SQLException if a database access error occurs or if the columnIndex is invalid */ @Override public void updateCharacterStream(final int columnIndex, final Reader x, final int length) throws SQLException { @@ -1258,12 +1385,16 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update object. + * Updates the designated column with an Object value. The scale or length + * is used for certain types of updates such as updating a numeric value + * or strings where precision or length needs to be specified. * - * @param columnIndex the column index - * @param x the x - * @param scaleOrLength the scale or length - * @throws SQLException the sql exception + * @param columnIndex the index of the column (starting at 1) to be updated + * @param x the new value for the column + * @param scaleOrLength for numeric and string types, this is the precision or + * length to be used; otherwise, ignored + * @throws SQLException if a database access error occurs or if this method + * is called on a closed result set */ @Override public void updateObject(final int columnIndex, final Object x, final int scaleOrLength) throws SQLException { @@ -1271,11 +1402,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update object. + * Updates the value of the designated column with the given object. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update, starting from 1 + * @param x the new value for the column, as an Object + * @throws SQLException if a database access error occurs or the column index is invalid */ @Override public void updateObject(final int columnIndex, final Object x) throws SQLException { @@ -1283,10 +1414,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update null. + * Updates the designated column with a null value. This method is typically used + * when updating database records to explicitly set a column to NULL. * - * @param columnLabel the column label - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with the SQL AS clause. + * If the SQL AS clause was not specified, the column name is used. + * @throws SQLException if a database access error occurs or the result set is not + * updatable. */ @Override public void updateNull(final String columnLabel) throws SQLException { @@ -1294,11 +1428,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update boolean. + * Updates the designated column with a boolean value. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified to be updated + * @param x the new boolean value to update the column with + * @throws SQLException if a database access error occurs or the columnLabel is not valid */ @Override public void updateBoolean(final String columnLabel, final boolean x) throws SQLException { @@ -1306,11 +1440,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update byte. + * Updates the designated column with a byte value. The update is applied to the current row + * of the ResultSet object. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated. It must match the column name as + * defined in the database table. + * @param x the new byte value that will be assigned to the specified column. + * @throws SQLException if a database access error occurs, the column label is not valid, or + * the ResultSet is in read-only mode. */ @Override public void updateByte(final String columnLabel, final byte x) throws SQLException { @@ -1318,11 +1455,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update short. + * Updates the designated column with a short value. + * The updated value is not immediately written to the database but is cached in the ResultSet until {@code updateRow()} is called. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated + * @param x the new column value as a short + * @throws SQLException if a database access error occurs, this method is called on a closed ResultSet, + * or if the columnLabel is not valid */ @Override public void updateShort(final String columnLabel, final short x) throws SQLException { @@ -1330,11 +1469,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update int. + * Updates the designated column with the specified integer value. + * This method is used to update the value of a column in the current row + * of the ResultSet object. The column is specified by its label. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated + * @param x the new integer value for the column + * @throws SQLException if a database access error occurs or the result set + * is not updatable */ @Override public void updateInt(final String columnLabel, final int x) throws SQLException { @@ -1342,23 +1484,21 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update long. - * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception - */ + * Updates the designated column with a specified long value. The updater methods are used + * to update column values in the current row or the insert row*/ @Override public void updateLong(final String columnLabel, final long x) throws SQLException { resultSet.updateLong(columnLabel, x); } /** - * Update float. + * Updates the designated column with a float value. The update is applied to + * the current row of the ResultSet object. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column that is to be updated + * @param x the new column value as a float + * @throws SQLException if an error occurs while updating the column or if the + * ResultSet is in an invalid state for the update */ @Override public void updateFloat(final String columnLabel, final float x) throws SQLException { @@ -1366,11 +1506,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update double. + * Updates the designated column with a specified double value. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified, which is the name of the column + * @param x the new column value as a double + * @throws SQLException if a database access error occurs, the result set is closed, + * or the columnLabel is not valid */ @Override public void updateDouble(final String columnLabel, final double x) throws SQLException { @@ -1378,11 +1519,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update big decimal. + * Updates the designated column with a {@code BigDecimal} value. + * The update is made to the underlying database as well as to the + * {@code ResultSet} object. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label of the column to update + * @param x the new {@code BigDecimal} value to assign to the column; + * can be {@code null} + * @throws SQLException if a database access error occurs */ @Override public void updateBigDecimal(final String columnLabel, final BigDecimal x) throws SQLException { @@ -1390,11 +1534,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update string. + * Updates the designated column with a new String value. + * The update is applicable to the current row of the ResultSet. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated + * @param x the new String value to update the column with + * @throws SQLException if a database access error occurs, + * the columnLabel is not valid or the ResultSet is in an invalid state */ @Override public void updateString(final String columnLabel, final String x) throws SQLException { @@ -1402,11 +1548,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update bytes. + * Updates the designated column with a byte array value. + * The updateBytes method should be used when updating columns in + * a ResultSet that is updateable. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated + * @param x the new column value stored as a byte array + * @throws SQLException if a database access error occurs or the ResultSet cannot be updated */ @Override public void updateBytes(final String columnLabel, final byte[] x) throws SQLException { @@ -1414,11 +1562,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update date. + * Updates the designated column with a Date value. This method is used to update + * the value of a specified column in the current row of the ResultSet with a Date object. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with the SQL AS clause. + * If the SQL AS clause was not specified, the label is the name of the column. + * @param x the new Date value to update the specified column with. This value can be null. + * @throws SQLException if a database access error occurs or the ResultSet is in read-only mode. */ @Override public void updateDate(final String columnLabel, final Date x) throws SQLException { @@ -1426,11 +1576,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update time. + * Updates the designated column with a {@code Time} value. + * The update is made to the current row of the {@link ResultSet} object. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label of the column to be updated + * @param x the new column {@code Time} value + * @throws SQLException if a database access error occurs or the columnLabel + * is not valid */ @Override public void updateTime(final String columnLabel, final Time x) throws SQLException { @@ -1438,11 +1590,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update timestamp. + * Updates the designated column with a Timestamp value. + * This method updates the column denoted by the specified column label + * in the current row of this ResultSet object. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated + * @param x the new column value as a Timestamp object; may be null + * @throws SQLException if a database access error occurs, the ResultSet is closed, + * or if the provided column label does not exist */ @Override public void updateTimestamp(final String columnLabel, final Timestamp x) throws SQLException { @@ -1450,12 +1605,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update ascii stream. + * Updates the designated column with an ASCII stream value. + * The input stream must contain ASCII characters. The stream must be fully read before + * setting the value to the designated column. * - * @param columnLabel the column label - * @param x the x - * @param length the length - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated + * @param x the input stream containing the ASCII data + * @param length the number of bytes in the input stream + * @throws SQLException if a database access error occurs or the columnLabel is not valid */ @Override public void updateAsciiStream(final String columnLabel, final InputStream x, final int length) throws SQLException { @@ -1463,12 +1620,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update binary stream. + * Updates the designated column with a binary input stream containing the specified number of bytes. + * This method is used to store binary data into a column. * - * @param columnLabel the column label - * @param x the x - * @param length the length - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with the update + * @param x the InputStream object that contains the binary data to be written + * @param length the number of bytes in the InputStream to be written to the column + * @throws SQLException if a database access error occurs or the columnLabel is not valid */ @Override public void updateBinaryStream(final String columnLabel, final InputStream x, final int length) throws SQLException { @@ -1476,12 +1634,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update character stream. + * Updates the designated column with a character stream value. The character stream will have + * a specified length in characters. * - * @param columnLabel the column label - * @param reader the reader - * @param length the length - * @throws SQLException the sql exception + * @param columnLabel the label of the column to update + * @param reader the java.io.Reader object that contains the character stream + * @param length the number of characters in the input stream + * @throws SQLException if a database access error occurs or the value is invalid */ @Override public void updateCharacterStream(final String columnLabel, final Reader reader, final int length) throws SQLException { @@ -1489,12 +1648,17 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update object. + * Updates the designated column with an object value. The update is applied to + * the specified column in the current row of this ResultSet object. * - * @param columnLabel the column label - * @param x the x - * @param scaleOrLength the scale or length - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with the update + * @param x the new column value, which must be an instance of a class supported by the JDBC driver + * or null to set the column value to SQL NULL + * @param scaleOrLength for an input parameter of SQL type DECIMAL or NUMERIC, this is the + * number of digits after the decimal point. For Java Object types + * InputStream and Reader, this is the length of the data in the stream or reader. + * For all other types, this value will be ignored. + * @throws SQLException if a database access error occurs or this method is called on a closed ResultSet */ @Override public void updateObject(final String columnLabel, final Object x, final int scaleOrLength) throws SQLException { @@ -1502,11 +1666,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update object. + * Updates the designated column with an Object value. + * The update is applied to the current row of the ResultSet, and will be written to the database + * when the ResultSet is updated. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label of the column to be updated + * @param x the new column value to be set, which can be any object type + * @throws SQLException if a database access error occurs or if the columnLabel is not valid */ @Override public void updateObject(final String columnLabel, final Object x) throws SQLException { @@ -1514,9 +1680,15 @@ public class TrimmingResultSet implements ResultSet { } /** - * Insert row. + * Inserts the current row into the database. * - * @throws SQLException the sql exception + * This method delegates the call to {@link ResultSet#insertRow()}. + * The method inserts the contents of the insert row into the database. + * It must be called while the cursor is positioned on the insert row. + * After the insertion, the cursor will remain positioned on the insert row. + * + * @throws SQLException if a database access error occurs or if this method + * is called when the cursor is not on the insert row. */ @Override public void insertRow() throws SQLException { @@ -1524,9 +1696,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update row. + * Updates the current row in the database using the current values of the + * ResultSet. This method writes any changes made to the result set to + * the database. * - * @throws SQLException the sql exception + * @throws SQLException if a database access error occurs, the ResultSet + * is in read-only mode, or if this method is called on a + * ResultSet that is not positioned on a valid row. */ @Override public void updateRow() throws SQLException { @@ -1534,9 +1710,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Delete row. + * Deletes the current row from the database. + * This method removes the current row in the ResultSet object + * and the corresponding row in the database. * - * @throws SQLException the sql exception + * @throws SQLException if a database access error occurs, + * the current row is not valid, or the ResultSet object is + * not updatable. */ @Override public void deleteRow() throws SQLException { @@ -1544,9 +1724,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Refresh row. + * Refreshes the current row of the ResultSet object to reflect the most recent + * changes made to the database. This method is particularly useful when + * concurrent updates are made to the underlying database, allowing the ResultSet + * to synchronize its data with the latest state of the database row. * - * @throws SQLException the sql exception + * @throws SQLException if a database access error occurs or if the ResultSet + * is closed. */ @Override public void refreshRow() throws SQLException { @@ -1554,9 +1738,15 @@ public class TrimmingResultSet implements ResultSet { } /** - * Cancel row updates. + * Cancels the updates made to the current row in this ResultSet object. * - * @throws SQLException the sql exception + * If the cancelRowUpdates method is called, the updates made to the current row + * will be discarded and no changes will be applied when the ResultSet is updated. + * + * This method delegates the call to the wrapped ResultSet's cancelRowUpdates method. + * + * @throws SQLException if a database access error occurs or this method is called + * on a closed ResultSet. */ @Override public void cancelRowUpdates() throws SQLException { @@ -1564,9 +1754,19 @@ public class TrimmingResultSet implements ResultSet { } /** - * Move to insert row. + * Moves the cursor to the insert row of the ResultSet object. + * The insert row is a special row associated with a ResultSet + * object that is used as a staging ground for building a row + * to be inserted. Only columns with a defined value can be updated + * when on the insert row. * - * @throws SQLException the sql exception + * This method provides a convenient way to prepare a row for insert + * operations. After setting the desired column values using the + * appropriate updater methods, the row can be committed to the + * database using the `insertRow` method of the ResultSet. + * + * @throws SQLException if a database access error occurs or + * if this method is called on a closed ResultSet. */ @Override public void moveToInsertRow() throws SQLException { @@ -1574,9 +1774,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Move to current row. + * Moves the cursor to the remembered cursor position, usually the position + * where the cursor was located prior to calling the {@code moveToInsertRow} method. + * This method is typically used when working with updatable result sets, allowing the + * cursor to return to its previous position after inserting a row. * - * @throws SQLException the sql exception + * @throws SQLException if a database access error occurs or this method is + * called on a ResultSet object that is not updatable. */ @Override public void moveToCurrentRow() throws SQLException { @@ -1584,10 +1788,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets statement. + * Retrieves the Statement object that produced this ResultSet object. * - * @return the statement - * @throws SQLException the sql exception + * @return the Statement object that produced this ResultSet or null if the result set was generated + * by a DatabaseMetaData method or if this method is called on a closed result set. + * @throws SQLException if a database access error occurs or this method is called on a closed result set. */ @Override public Statement getStatement() throws SQLException { @@ -1595,12 +1800,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update ascii stream. + * Updates the designated column with an ASCII stream value. + * The data will be read from the provided InputStream and should match the specified length. + * This method can be used to update a column in the current row of a ResultSet object. * - * @param columnIndex the column index - * @param x the x - * @param length the length - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update, starting from 1 + * @param x the InputStream object containing the ASCII stream data + * @param length the length of the ASCII stream in bytes + * @throws SQLException if a database access error occurs or the ResultSet is not updatable */ @Override public void updateAsciiStream(final int columnIndex, final InputStream x, final long length) throws SQLException { @@ -1608,12 +1815,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update binary stream. + * Updates the designated column with a binary stream value. The data will be read from the given + * InputStream object starting from the current position to the specified length. The stream must + * provide at least the number of bytes specified by the length parameter. * - * @param columnIndex the column index - * @param x the x - * @param length the length - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update (1-based index) + * @param x the InputStream containing the binary data + * @param length the number of bytes to write from the InputStream + * @throws SQLException if a database access error occurs or if any argument is invalid */ @Override public void updateBinaryStream(final int columnIndex, final InputStream x, final long length) throws SQLException { @@ -1621,12 +1830,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update character stream. + * Updates the designated column with a character stream value. + * The data will be read from the provided Reader object. * - * @param columnIndex the column index - * @param x the x - * @param length the length - * @throws SQLException the sql exception + * @param columnIndex the 1-based index of the column to update + * @param x the Reader object that contains the new character stream value + * @param length the number of characters in the stream + * @throws SQLException if a database access error occurs, the column index is out of bounds, + * or if the provided Reader is null */ @Override public void updateCharacterStream(final int columnIndex, final Reader x, final long length) throws SQLException { @@ -1634,12 +1845,15 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update ascii stream. + * Updates the designated column with an ASCII stream value. The stream must contain + * ASCII characters and is read to the specified number of characters. If the designated + * column does not support ASCII stream updates, a SQLException will be thrown. * - * @param columnLabel the column label - * @param x the x - * @param length the length - * @throws SQLException the sql exception + * @param columnLabel the label of the column to be updated + * @param x the InputStream containing the ASCII data + * @param length the number of bytes to read from the InputStream + * @throws SQLException if a database access error occurs, if the columnLabel does not exist, + * or if this method is called on a closed result set */ @Override public void updateAsciiStream(final String columnLabel, final InputStream x, final long length) throws SQLException { @@ -1647,12 +1861,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update binary stream. + * Updates the designated column with a binary stream value. + * The data will be read from the supplied {@code InputStream} and written to the column, + * according to the specified length. * - * @param columnLabel the column label - * @param x the x - * @param length the length - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated + * @param x the {@code InputStream} object that contains the new column value + * @param length the number of bytes in the stream to read + * @throws SQLException if a database access error occurs or if the columnLabel is not valid */ @Override public void updateBinaryStream(final String columnLabel, final InputStream x, final long length) throws SQLException { @@ -1660,12 +1876,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update character stream. + * Updates the designated column with a character stream value. + * The data in the stream will have the specified length. * - * @param columnLabel the column label - * @param reader the reader - * @param length the length - * @throws SQLException the sql exception + * @param columnLabel the label for the column name + * @param reader the java.io.Reader object that contains the data to set the column value to + * @param length the number of characters in the stream + * @throws SQLException if the columnLabel is not valid, a database access error occurs, + * the result set is closed, or if this method is called on a read-only result set */ @Override public void updateCharacterStream(final String columnLabel, final Reader reader, final long length) throws SQLException { @@ -1673,11 +1891,16 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update blob. + * Updates the designated column with a {@link Blob} value. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * The updateBlob method updates the current row's column with the + * specified Blob object. The update is not persisted in the database + * until the {@code updateRow()} method is called. + * + * @param columnIndex the index of the column to update, starting from 1 + * @param x the new Blob value to assign to the column + * @throws SQLException if a database access error occurs or the result set + * is not updatable */ @Override public void updateBlob(final int columnIndex, final Blob x) throws SQLException { @@ -1685,11 +1908,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update blob. + * Updates the designated column with a Blob value. The updater methods are + * used to update column values in the current row or the insert row. The + * update is not applied to the database until the method `updateRow` is called. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with the SQL query. + * @param x the Blob object that contains the data to set the value in the specified column. + * @throws SQLException if a database access error occurs or this method is + * called on a closed ResultSet. */ @Override public void updateBlob(final String columnLabel, final Blob x) throws SQLException { @@ -1697,11 +1923,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update clob. + * Updates the designated column with a Clob value. The column is specified by its index, + * and the value is provided as a Clob object. This method updates the Clob value on the + * underlying database structure. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update, starting from 1. + * @param x the Clob object containing the new value to set for the specified column. + * @throws SQLException if a database access error occurs or the operation is not supported. */ @Override public void updateClob(final int columnIndex, final Clob x) throws SQLException { @@ -1709,11 +1937,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update clob. + * Updates the designated column with a Clob value. The updater methods are used to update column + * values in the result set, which can then be updated in the underlying database. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified in the SQL query + * @param x the Clob value to update the column with + * @throws SQLException if a database access error occurs or the result set is in read-only mode */ @Override public void updateClob(final String columnLabel, final Clob x) throws SQLException { @@ -1721,11 +1950,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update array. + * Updates the designated column with an Array value. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the index of the column to be updated, where the first column is 1 + * @param x the new Array value to update the column with + * @throws SQLException if a database access error occurs or the column index is invalid */ @Override public void updateArray(final int columnIndex, final Array x) throws SQLException { @@ -1733,11 +1962,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update array. + * Updates the designated column with an Array value. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated + * @param x the Array object to update the column with + * @throws SQLException if a database access error occurs or the columnLabel is invalid */ @Override public void updateArray(final String columnLabel, final Array x) throws SQLException { @@ -1745,11 +1974,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets row id. + * Retrieves the RowId object that corresponds to the specified column index in the result set. * - * @param columnIndex the column index - * @return the row id - * @throws SQLException the sql exception + * @param columnIndex the column index, starting from 1, for which the RowId is to be retrieved + * @return the RowId value for the specified column index + * @throws SQLException if a database access error occurs or the columnIndex is invalid */ @Override public RowId getRowId(final int columnIndex) throws SQLException { @@ -1757,11 +1986,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets row id. + * Retrieves the RowId object corresponding to the specified column label. * - * @param columnLabel the column label - * @return the row id - * @throws SQLException the sql exception + * @param columnLabel the label for the column from which to retrieve the RowId + * @return the RowId object for the specified column + * @throws SQLException if a database access error occurs or the column label is invalid */ @Override public RowId getRowId(final String columnLabel) throws SQLException { @@ -1769,11 +1998,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update row id. + * Updates the designated column with a RowId value. + * The updateRowId method provides the capability to update the column with a RowId object + * which represents the SQL ROWID data type. The update is performed for the current row + * of the ResultSet. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the 1-based index of the column to be updated + * @param x the RowId object containing the new value for the column + * @throws SQLException if a database access error occurs or the result set is not updatable */ @Override public void updateRowId(final int columnIndex, final RowId x) throws SQLException { @@ -1781,11 +2013,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update row id. + * Updates the designated column with a new RowId value. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified by the SQL AS clause. + * If the SQL AS clause was not specified, the name of the column is used. + * @param x the new RowId value to update in the specified column + * @throws SQLException if a database access error occurs or the method is called on a closed ResultSet */ @Override public void updateRowId(final String columnLabel, final RowId x) throws SQLException { @@ -1793,10 +2026,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets holdability. + * Retrieves the current holdability of ResultSet objects created using this method. * - * @return the holdability - * @throws SQLException the sql exception + * @return an integer representing the holdability of ResultSet objects. The value is + * either ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT. + * @throws SQLException if a database access error occurs. */ @Override public int getHoldability() throws SQLException { @@ -1804,10 +2038,10 @@ public class TrimmingResultSet implements ResultSet { } /** - * Is closed boolean. + * Checks if the {@code ResultSet} is closed. * - * @return the boolean - * @throws SQLException the sql exception + * @return {@code true} if the {@code ResultSet} is closed; {@code false} otherwise. + * @throws SQLException if a database access error occurs. */ @Override public boolean isClosed() throws SQLException { @@ -1815,11 +2049,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update n string. + * Updates the designated column with a String value. The column index specifies + * the column to be updated, and the String value provided will be stored in the + * appropriate column of the underlying database. * - * @param columnIndex the column index - * @param nString the n string - * @throws SQLException the sql exception + * @param columnIndex the first column is 1, the second is 2, and so on + * @param nString the new value for the designated column. Can be null. + * @throws SQLException if a database access error occurs or this method is + * called on a closed ResultSet */ @Override public void updateNString(final int columnIndex, final String nString) throws SQLException { @@ -1827,11 +2064,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update n string. + * Updates the designated column with the given string value. The updateNString method should + * be used when the column stores a national character set value. * - * @param columnLabel the column label - * @param nString the n string - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated + * @param nString the new column value of type String + * @throws SQLException if a database access error occurs or if the method is called on a closed result set */ @Override public void updateNString(final String columnLabel, final String nString) throws SQLException { @@ -1839,11 +2077,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update n clob. + * Updates the designated column with a given NClob value. + * Updates the NClob object in the ResultSet to reflect changes. * - * @param columnIndex the column index - * @param nClob the n clob - * @throws SQLException the sql exception + * @param columnIndex the column index in the ResultSet, starting at 1, which needs to be updated + * @param nClob the NClob object that holds the new value to assign to the column + * @throws SQLException if a database access error occurs or the ResultSet is in a read-only state */ @Override public void updateNClob(final int columnIndex, final NClob nClob) throws SQLException { @@ -1851,11 +2090,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update n clob. + * Updates the designated column with a given NClob object. The column is specified by + * its label, and the input NClob object will be used to update the value in the + * ResultSet. This method can be used to update NClob data in a database. * - * @param columnLabel the column label - * @param nClob the n clob - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated + * @param nClob the NClob object containing the data to update the column with + * @throws SQLException if a database access error occurs or this method is called + * on a closed ResultSet */ @Override public void updateNClob(final String columnLabel, final NClob nClob) throws SQLException { @@ -1863,11 +2105,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets n clob. + * Retrieves the value of the specified column as a {@code NClob} object. * - * @param columnIndex the column index - * @return the n clob - * @throws SQLException the sql exception + * @param columnIndex the index of the column from which the value is to be retrieved, + * starting at 1 for the first column. + * @return the {@code NClob} object representing the value of the specified column, + * or {@code null} if the column contains SQL {@code NULL}. + * @throws SQLException if a database access error occurs or if the column index is invalid. */ @Override public NClob getNClob(final int columnIndex) throws SQLException { @@ -1875,11 +2119,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets n clob. + * Retrieves the value of the designated column as a {@link NClob} object. * - * @param columnLabel the column label - * @return the n clob - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with the SQL AS clause. + * If the SQL AS clause was not specified, then the label is the name of the column. + * @return the value of the designated column as a {@link NClob} object; + * if the value is SQL NULL, the method returns null. + * @throws SQLException if a database access error occurs or this method is called on a closed result set. */ @Override public NClob getNClob(final String columnLabel) throws SQLException { @@ -1887,11 +2133,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets sqlxml. + * Retrieves the value of the designated column in the current row of this + * ResultSet object as a SQLXML object. * - * @param columnIndex the column index - * @return the sqlxml - * @throws SQLException the sql exception + * @param columnIndex the column index, starting from 1 for the first column + * @return the SQLXML value of the specified column in the current row + * @throws SQLException if a database access error occurs or the column index is not valid */ @Override public SQLXML getSQLXML(final int columnIndex) throws SQLException { @@ -1899,11 +2146,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets sqlxml. + * Retrieves the value of the designated column as a {@code SQLXML} object. * - * @param columnLabel the column label - * @return the sqlxml - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified in the query. + * @return the {@code SQLXML} object representing the SQL XML value of the specified column. + * @throws SQLException if there is an error accessing the SQL data or if the column does not support SQLXML values. */ @Override public SQLXML getSQLXML(final String columnLabel) throws SQLException { @@ -1911,11 +2158,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update sqlxml. + * Updates the designated column with the given SQLXML value. * - * @param columnIndex the column index - * @param xmlObject the xml object - * @throws SQLException the sql exception + * @param columnIndex the first column is 1, the second is 2, and so on. + * @param xmlObject the SQLXML object representing the XML value to update the column with. + * @throws SQLException if a database access error occurs or if the columnIndex is invalid. */ @Override public void updateSQLXML(final int columnIndex, final SQLXML xmlObject) throws SQLException { @@ -1923,11 +2170,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update sqlxml. + * Updates the designated column with an SQLXML value. The update is performed + * on the current row of the ResultSet. * - * @param columnLabel the column label - * @param xmlObject the xml object - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with the SQL XML data type. + * @param xmlObject the SQLXML object containing the data to set in the specified column. + * @throws SQLException if an error occurs while updating the SQLXML value or if the ResultSet is in read-only mode. */ @Override public void updateSQLXML(final String columnLabel, final SQLXML xmlObject) throws SQLException { @@ -1935,12 +2183,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update n character stream. + * Updates the designated column with a character stream value. The data will be read + * from the provided Reader object and should have a specified length. * - * @param columnIndex the column index - * @param x the x - * @param length the length - * @throws SQLException the sql exception + * @param columnIndex the column index (1-based) indicating the column to be updated + * @param x the Reader object that contains the new character stream data + * @param length the number of characters in the stream to be read + * @throws SQLException if a database access error occurs or the columnIndex is invalid */ @Override public void updateNCharacterStream(final int columnIndex, final Reader x, final long length) throws SQLException { @@ -1948,12 +2197,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update n character stream. + * Updates the designated column with a character stream value. + * The data will be read from the provided Reader and will have the specified length. * - * @param columnLabel the column label - * @param reader the reader - * @param length the length - * @throws SQLException the sql exception + * @param columnLabel the label for the column to update + * @param reader the java.io.Reader object from which the data will be read + * @param length the length of the stream in characters + * @throws SQLException if a database access error occurs or the column label is invalid */ @Override public void updateNCharacterStream(final String columnLabel, final Reader reader, final long length) throws SQLException { @@ -1961,11 +2211,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update n character stream. + * Updates the designated column with a character stream value. The data will be read from the provided + * Reader object and used to update the column indicated by the columnIndex parameter. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update, where the first column is 1 + * @param x the Reader object that contains the new character stream data + * @throws SQLException if a database access error occurs or the result set is in a read-only mode */ @Override public void updateNCharacterStream(final int columnIndex, final Reader x) throws SQLException { @@ -1973,11 +2224,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update n character stream. + * Updates the designated column with a character stream value, which will then + * be written to the database. The column specified by the given label will be updated + * with the data provided by the Reader object. * - * @param columnLabel the column label - * @param reader the reader - * @throws SQLException the sql exception + * @param columnLabel the label for the column that needs to be updated. + * @param reader the java.io.Reader object containing the data to set the column value. + * @throws SQLException if a database access error occurs or the columnLabel is invalid. */ @Override public void updateNCharacterStream(final String columnLabel, final Reader reader) throws SQLException { @@ -1985,12 +2238,15 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update blob. + * Updates the designated column with a binary stream value, which will have + * the specified number of bytes. The data will be read from the provided + * {@code InputStream}. * - * @param columnIndex the column index - * @param inputStream the input stream - * @param length the length - * @throws SQLException the sql exception + * @param columnIndex the first column is 1, the second is 2, ... + * @param inputStream the {@code InputStream} object containing the binary data + * @param length the number of bytes in the binary data + * @throws SQLException if a database access error occurs or if the column + * index is invalid */ @Override public void updateBlob(final int columnIndex, final InputStream inputStream, final long length) throws SQLException { @@ -1998,12 +2254,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update blob. + * Updates the designated column with an InputStream value, which will be written to the database as a Blob. * - * @param columnLabel the column label - * @param inputStream the input stream - * @param length the length - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated + * @param inputStream the InputStream containing the Blob data + * @param length the number of bytes in the InputStream + * @throws SQLException if a database access error occurs or the columnLabel is invalid */ @Override public void updateBlob(final String columnLabel, final InputStream inputStream, final long length) throws SQLException { @@ -2011,11 +2267,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update blob. + * Updates the designated column with a binary stream value. + * The input stream is used to supply the binary data for the value to be set in the column. * - * @param columnIndex the column index - * @param inputStream the input stream - * @throws SQLException the sql exception + * @param columnIndex the first column is 1, the second is 2, and so on + * @param inputStream the InputStream containing the binary data to set + * @throws SQLException if the columnIndex is invalid, if a database access error occurs, + * or if this method is called on a closed result set */ @Override public void updateBlob(final int columnIndex, final InputStream inputStream) throws SQLException { @@ -2023,11 +2281,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update blob. + * Updates the designated column with an InputStream value, which will be + * set as a BLOB in the underlying database. * - * @param columnLabel the column label - * @param inputStream the input stream - * @throws SQLException the sql exception + * @param columnLabel the label for the column whose value will be set + * @param inputStream the InputStream containing the binary data to set as a BLOB + * @throws SQLException if a database access error occurs or the specified + * columnLabel is not valid */ @Override public void updateBlob(final String columnLabel, final InputStream inputStream) throws SQLException { @@ -2035,12 +2295,10 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update clob. + * Updates the designated column with a Clob value. The data will be read from the provided Reader + * object for the specified number of characters. * - * @param columnIndex the column index - * @param reader the reader - * @param length the length - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update, starting from 1 */ @Override public void updateClob(final int columnIndex, final Reader reader, final long length) throws SQLException { @@ -2048,12 +2306,17 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update clob. + * Updates the designated column with a character stream containing a CLOB value. + * The data in the stream will be read into the CLOB value, starting at the beginning. + * The length parameter indicates the number of characters to read from the reader. * - * @param columnLabel the column label - * @param reader the reader - * @param length the length - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with the SQL AS clause + * or the column name + * @param reader the java.io.Reader object containing the data to set as the CLOB value + * @param length the length of the data to be written to the CLOB column in characters + * @throws SQLException if a database access error occurs, this method is called on a closed result set, + * if the designated column does not have a CLOB data type, + * or if the length specified is invalid */ @Override public void updateClob(final String columnLabel, final Reader reader, final long length) throws SQLException { @@ -2061,11 +2324,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update clob. + * Updates the designated Clob column using the data provided by a Reader object. + * The new data will overwrite the existing Clob value at the specified column index. * - * @param columnIndex the column index - * @param reader the reader - * @throws SQLException the sql exception + * @param columnIndex the index of the column to be updated, starting from 1 + * @param reader the Reader object that contains the new Clob data to set + * @throws SQLException if a database access error occurs or the column index is invalid */ @Override public void updateClob(final int columnIndex, final Reader reader) throws SQLException { @@ -2073,11 +2337,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update clob. + * Updates the designated Clob column with the given character stream reader. * - * @param columnLabel the column label - * @param reader the reader - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with a SQL identifier + * @param reader the Reader object that contains the new Clob data + * @throws SQLException if a database access error occurs or the columnLabel is not valid */ @Override public void updateClob(final String columnLabel, final Reader reader) throws SQLException { @@ -2085,12 +2349,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update n clob. + * Updates the designated column with a character stream value, which will have + * a specified number of characters, in the current row of this ResultSet object. * - * @param columnIndex the column index - * @param reader the reader - * @param length the length - * @throws SQLException the sql exception + * @param columnIndex the column index (starting from 1) indicating the column to be updated + * @param reader the java.io.Reader object that contains the data to be written to the NClob column + * @param length the number of characters in the stream to be written to the column + * @throws SQLException if a database access error occurs, second parameter is null, or this method is + * called on a closed ResultSet */ @Override public void updateNClob(final int columnIndex, final Reader reader, final long length) throws SQLException { @@ -2098,12 +2364,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update n clob. + * Updates the designated column with a new CLOB value. The data will be read from the supplied Reader + * and will have the specified length. The column is identified using its label. * - * @param columnLabel the column label - * @param reader the reader - * @param length the length - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated + * @param reader the Reader object that contains the data to update the CLOB value + * @param length the number of characters in the Reader to be read + * @throws SQLException if a database access error occurs or the columnLabel is not valid */ @Override public void updateNClob(final String columnLabel, final Reader reader, final long length) throws SQLException { @@ -2111,11 +2378,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update n clob. + * Updates the designated NClob column with a Reader object. The data in the Reader object + * will be written to the NClob value that is being updated. This method is typically used + * when working with large NClob data. * - * @param columnIndex the column index - * @param reader the reader - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update (1-based index) + * @param reader the java.io.Reader object containing the data to set the NClob value + * @throws SQLException if a database access error occurs or the method is called on + * a closed ResultSet */ @Override public void updateNClob(final int columnIndex, final Reader reader) throws SQLException { @@ -2123,11 +2393,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update n clob. + * Updates the designated column with a new NClob value. The data is read + * from the provided Reader object. * - * @param columnLabel the column label - * @param reader the reader - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated + * @param reader the java.io.Reader object from which the NClob value will be read + * @throws SQLException if a database access error occurs or the Reader object is null */ @Override public void updateNClob(final String columnLabel, final Reader reader) throws SQLException { @@ -2135,13 +2406,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets object. + * Retrieves an object from the specified column index in the result set and converts it to the specified type. * - * @param the type parameter - * @param columnIndex the column index - * @param type the type - * @return the object - * @throws SQLException the sql exception + * @param the type of the object to be retrieved + * @param columnIndex the index of the column from which the object is to be retrieved, starting at 1 + * @param type the Class object representing the type to which the object should be converted + * @return the object from the specified column converted to the specified type + * @throws SQLException if a database access error occurs or this method is called on a closed result set */ @Override public T getObject(final int columnIndex, final Class type) throws SQLException { @@ -2149,13 +2420,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets object. + * Retrieves an object from the specified column label in the result set and casts it to the provided type. * - * @param the type parameter - * @param columnLabel the column label - * @param type the type - * @return the object - * @throws SQLException the sql exception + * @param columnLabel the label for the column from which the object will be retrieved + * @param type the class of the object to be retrieved + * @return the object retrieved from the specified column, cast to the specified type + * @throws SQLException if a database access error occurs or the column label is not valid */ @Override public T getObject(final String columnLabel, final Class type) throws SQLException { @@ -2163,14 +2433,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update object. + * Updates the designated column with an object value. The update will be applied to the column + * specified by the given column index. This method allows specifying a SQL target type and a scale + * or length for the object being updated. * - * @param columnIndex the column index - * @param x the x - * @param targetSqlType the target sql type - * @param scaleOrLength the scale or length - * @throws SQLException the sql exception - */ + * @param columnIndex the index of the column to update*/ @Override public void updateObject(final int columnIndex, final Object x, final SQLType targetSqlType, final int scaleOrLength) throws SQLException { @@ -2178,13 +2445,16 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update object. + * Updates the designated column with an object value. + * The object will be converted to the specified SQL type before being updated. * - * @param columnLabel the column label - * @param x the x - * @param targetSqlType the target sql type - * @param scaleOrLength the scale or length - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated + * @param x the object containing the value to be stored in the specified column + * @param targetSqlType the SQL type to convert the object to + * @param scaleOrLength for numeric data, this is the number of digits after the decimal point; + * for non-numeric data, this is the length of the data + * @throws SQLException if a database access error occurs, this method is called on a closed ResultSet, + * or the target SQL type is invalid */ @Override public void updateObject(final String columnLabel, final Object x, final SQLType targetSqlType, final int scaleOrLength) @@ -2193,12 +2463,15 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update object. + * Updates the designated column with an object value. The update is made to + * the current row of the ResultSet object. This method allows specifying + * the column index and the target SQL type for the object being updated. * - * @param columnIndex the column index - * @param x the x - * @param targetSqlType the target sql type - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update, starting from 1 + * @param x the object containing the new column value + * @param targetSqlType the SQL type to be sent to the database + * @throws SQLException if a database access error occurs or if the specified + * parameters are invalid */ @Override public void updateObject(final int columnIndex, final Object x, final SQLType targetSqlType) throws SQLException { @@ -2206,12 +2479,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update object. + * Updates the value of the designated column with the given column label in the current row of this + * ResultSet object to the provided Java object. The data will be converted to the SQL type specified + * by the given targetSqlType parameter before updating. * - * @param columnLabel the column label - * @param x the x - * @param targetSqlType the target sql type - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated + * @param x the new column value + * @param targetSqlType the SQL type to be used for data conversion before updating + * @throws SQLException if a database access error occurs or if the columnLabel is not valid */ @Override public void updateObject(final String columnLabel, final Object x, final SQLType targetSqlType) throws SQLException { @@ -2219,11 +2494,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update ascii stream. + * Updates the designated column with an ASCII InputStream. + * The stream must contain only ASCII characters. The driver reads the stream to the end. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the index of the column to update, starting from 1. + * @param x the InputStream containing ASCII data to set in the specified column. + * @throws SQLException if a database access error occurs or the columnIndex is invalid. */ @Override public void updateAsciiStream(final int columnIndex, final InputStream x) throws SQLException { @@ -2231,11 +2507,14 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update binary stream. + * Updates the designated column with a binary stream value. + * The data provided in the stream replaces the existing value of the column + * at the specified index in the current row of the ResultSet. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the index of the column to be updated, where the first column is 1 + * @param x the InputStream containing the binary data to set in the column + * @throws SQLException if a database access error occurs or the ResultSet is in a state + * that does not permit the update */ @Override public void updateBinaryStream(final int columnIndex, final InputStream x) throws SQLException { @@ -2243,11 +2522,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update character stream. + * Updates the designated column with a new character stream value. + * The data will be read from the provided Reader object and written to the database. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the index of the column to be updated, starting from 1 + * @param x the Reader object containing the new character stream value + * @throws SQLException if a database access error occurs or the columnIndex is invalid */ @Override public void updateCharacterStream(final int columnIndex, final Reader x) throws SQLException { @@ -2255,11 +2535,15 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update ascii stream. + * Updates the designated column with an ASCII stream. + * The data will be read from the input stream as needed until the end of the stream is reached. + * This method can be used to update columns in the current row or the insert row. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified with the SQL AS clause. + * If the SQL AS clause was not specified, the label will default to the column name. + * @param x the InputStream object containing the ASCII stream data to set in the column + * @throws SQLException if a database access error occurs, this method is called on a closed result set, + * or if the ResultSet concurrency is CONCUR_READ_ONLY */ @Override public void updateAsciiStream(final String columnLabel, final InputStream x) throws SQLException { @@ -2267,11 +2551,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update binary stream. + * Updates the designated column with a binary stream value. The column is specified by the column label. + * The data in the InputStream can be used as an updated value for the column. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column to be updated. + * @param x the InputStream containing the binary stream data to update the column with. + * @throws SQLException if a database access error occurs or the column label is not valid. */ @Override public void updateBinaryStream(final String columnLabel, final InputStream x) throws SQLException { @@ -2279,11 +2564,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update character stream. + * Updates the designated column with a new character stream value. + * The data will be read from the provided Reader object and sent to the database. * - * @param columnLabel the column label - * @param reader the reader - * @throws SQLException the sql exception + * @param columnLabel the label for the column that is to be updated + * @param reader the Reader object containing the data to set the specified column to + * @throws SQLException if a database access error occurs, this method is called on a closed result set, + * or the columnLabel is invalid */ @Override public void updateCharacterStream(final String columnLabel, final Reader reader) throws SQLException { @@ -2291,23 +2578,21 @@ public class TrimmingResultSet implements ResultSet { } /** - * Gets url. + * Retrieves the value of the designated column in the current row of this ResultSet object + * as a java.net.URL object. * - * @param columnIndex the column index - * @return the url - * @throws SQLException the sql exception - */ + * @param columnIndex the index of the column from which the URL is to be retrieved, where*/ @Override public URL getURL(final int columnIndex) throws SQLException { return resultSet.getURL(columnIndex); } /** - * Gets url. + * Retrieves the value of the designated column as a URL object. * - * @param columnLabel the column label - * @return the url - * @throws SQLException the sql exception + * @param columnLabel the label for the column, which is the column name defined during table creation + * @return the column value as a URL object, or null if the SQL value is SQL NULL + * @throws SQLException if a database access error occurs or the columnLabel is not valid */ @Override public URL getURL(final String columnLabel) throws SQLException { @@ -2315,11 +2600,16 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update ref. + * Updates the designated column with a Ref value. + * The updater methods are used to update column values in the current row + * or the insert row. The new row value will be updated into the database + * when the method updateRow is called. * - * @param columnIndex the column index - * @param x the x - * @throws SQLException the sql exception + * @param columnIndex the first column is 1, the second is 2, and so on + * @param x the new column value; must be a Ref object + * @throws SQLException if a database access error occurs, if the result set + * concurrency is CONCUR_READ_ONLY, or if this method + * is called on a closed result set */ @Override public void updateRef(final int columnIndex, final Ref x) throws SQLException { @@ -2327,11 +2617,13 @@ public class TrimmingResultSet implements ResultSet { } /** - * Update ref. + * Updates the designated column with a Ref value. + * This method should be called when updating a column in a ResultSet with a Ref object. * - * @param columnLabel the column label - * @param x the x - * @throws SQLException the sql exception + * @param columnLabel the label for the column specified in the query, used to identify the column being updated + * @param x the Ref object containing the value to update the column with + * @throws SQLException if a database access error occurs, the ResultSet is in a read-only mode, + * or if this method is called on a non-updatable ResultSet */ @Override public void updateRef(final String columnLabel, final Ref x) throws SQLException { @@ -2339,11 +2631,11 @@ public class TrimmingResultSet implements ResultSet { } /** - * Is wrapper for boolean. + * Checks if this object wraps an implementation of the specified interface. * - * @param iface the iface - * @return the boolean - * @throws SQLException the sql exception + * @param iface the interface to check if the object implements or wraps. + * @return true if this object is a wrapper for the specified interface; false otherwise. + * @throws SQLException if a database access error occurs. */ @Override public boolean isWrapperFor(final Class iface) throws SQLException { @@ -2351,12 +2643,12 @@ public class TrimmingResultSet implements ResultSet { } /** - * Unwrap t. + * Unwraps this instance to provide an implementation of the specified interface. * - * @param the type parameter - * @param iface the iface - * @return the t - * @throws SQLException the sql exception + * @param the type of the class modeled by the specified interface + * @param iface the class of the interface to be unwrapped + * @return an instance of the specified interface, which this object implements + * @throws SQLException if no object implements the specified interface or if an error occurs */ @Override public T unwrap(final Class iface) throws SQLException { diff --git a/encryption/pom.xml b/encryption/pom.xml new file mode 100644 index 0000000..d118b35 --- /dev/null +++ b/encryption/pom.xml @@ -0,0 +1,46 @@ + + + 4.0.0 + + + de.neitzel.lib + neitzellib + 1.0-SNAPSHOT + + + encryption + + + + ${project.artifactId} + ${project.artifactId} + ${project.artifactId} + ${project.artifactId}-${project.version} + + + + + com.idealista + format-preserving-encryption + 1.0.0 + + + + + ${jar.filename} + + + + com.github.spotbugs + spotbugs-maven-plugin + + + + org.apache.maven.plugins + maven-pmd-plugin + + + + diff --git a/encryption/src/main/java/de/neitzel/encryption/BaseAlphabet.java b/encryption/src/main/java/de/neitzel/encryption/BaseAlphabet.java new file mode 100644 index 0000000..78bc4be --- /dev/null +++ b/encryption/src/main/java/de/neitzel/encryption/BaseAlphabet.java @@ -0,0 +1,41 @@ +package de.neitzel.encryption; + +import com.idealista.fpe.config.Alphabet; + +public abstract class BaseAlphabet implements Alphabet { + /** + * Replaces illegal characters of a string with a given replacement character + * @param text Text to check. + * @param replacement Replacement character. + * @return String in which all characters was replaced. + */ + public String replaceIllegalCharacters(String text, char replacement) { + // Validate + if (!isValidCharacter(replacement)) throw new IllegalArgumentException("replacement"); + + StringBuilder result = new StringBuilder(); + for (char ch: text.toCharArray()) { + if (isValidCharacter(ch)){ + result.append(ch); + } else { + result.append(replacement); + } + } + return result.toString(); + } + + /** + * Checks if a given Character is part of the alphabet. + * @param character Character to check. + * @return true if character is valid, else false. + */ + public boolean isValidCharacter(char character) { + // Compare with all characters + for (char ch : availableCharacters()) { + if (ch == character) return true; + } + + // Character not found. + return false; + } +} diff --git a/encryption/src/main/java/de/neitzel/encryption/FF1Encryption.java b/encryption/src/main/java/de/neitzel/encryption/FF1Encryption.java new file mode 100644 index 0000000..0134e2c --- /dev/null +++ b/encryption/src/main/java/de/neitzel/encryption/FF1Encryption.java @@ -0,0 +1,140 @@ +package de.neitzel.encryption; + +import com.idealista.fpe.FormatPreservingEncryption; +import com.idealista.fpe.builder.FormatPreservingEncryptionBuilder; +import com.idealista.fpe.config.Domain; +import com.idealista.fpe.config.LengthRange; + +import javax.crypto.KeyGenerator; +import java.security.NoSuchAlgorithmException; +import java.util.Random; + +/** + * Helper class to deal with FF1Encryption using com.idealista:format-preserving-encryption:1.0.0. + */ +public class FF1Encryption { + + /** + * Key to use for all encryption / unencryption + */ + private byte[] key; + + /** + * Should to small strings be ignored? + * + * If this is set to true, small strings (less than 2 characters) will not be encrypted! + */ + private boolean ignoreToShortStrings; + + /** + * tweak to use for encryption + */ + private byte[] tweak; + + /** + * Domain used for encryption + */ + private Domain domain; + + /** + * Format preserving encryption to use. + */ + private FormatPreservingEncryption encryption; + + /** + * Minimum length of a string. + */ + private int minLength; + + /** + * Creates a new instance of FF1Encryption + * @param key AES key to use. + * @param tweak tweak to use for encryption / decryption + * @param ignoreToShortStrings Ignore strings that are to short. + */ + public FF1Encryption(byte[] key, byte[] tweak, boolean ignoreToShortStrings) { + this(key, tweak, ignoreToShortStrings, new MainDomain(), 2, 1024); + } + + /** + * Creates a new instance of FF1Encryption + * @param key AES key to use. + * @param tweak tweak to use for encryption / decryption + * @param ignoreToShortStrings Ignore strings that are to short. + * @param domain Domain to use for encryption + * @param minLength Minimum length of string. + * @param maxLength Maximum length of string. + */ + public FF1Encryption(byte[] key, byte[] tweak, boolean ignoreToShortStrings, Domain domain, int minLength, int maxLength) { + this.key = key; + this.tweak = tweak; + this.ignoreToShortStrings = ignoreToShortStrings; + this.domain = domain; + this.minLength = minLength; + + encryption = FormatPreservingEncryptionBuilder + .ff1Implementation().withDomain(domain) + .withDefaultPseudoRandomFunction(key) + .withLengthRange(new LengthRange(minLength, maxLength)) + .build(); + } + + /** + * Encrypts a given text. + * @param plainText Unencrypted text. + * @return Encrypted text. + */ + public String encrypt(String plainText) { + // Handle null + if (plainText == null) return null; + + // Handle short strings + if (plainText.length() < minLength && ignoreToShortStrings) return plainText; + + // Return encrypted text. + return encryption.encrypt(plainText, tweak); + } + + /** + * Decrypt a given text. + * @param cipherText Encrypted text. + * @return Decrypted text. + */ + public String decrypt(String cipherText) { + // Handle null + if (cipherText == null) return null; + + // Handle short strings + if (cipherText.length() < minLength && ignoreToShortStrings) return cipherText; + + // Return decrypted text. + return encryption.decrypt(cipherText, tweak); + } + + /** + * Creates a new AES key woth the given length. + * @param length Length of the key in bits. Must be 128, 192 or 256 bits + * @return Byte array of the new key. + */ + public static byte[] createNewKey(int length) { + try { + KeyGenerator keyGen = KeyGenerator.getInstance("AES"); + keyGen.init(length); // for example + return keyGen.generateKey().getEncoded(); + } catch (NoSuchAlgorithmException ex) { + throw new RuntimeException(ex); + } + } + + /** + * Creates a new tweak of the given length. + * @param length Number of bytes the new teeak should have. + * @return byte array with the new tweak. + */ + public static byte[] createNewTweak(int length) { + Random random = new Random(); + byte[] key = new byte[length]; + random.nextBytes(key); + return key; + } +} diff --git a/encryption/src/main/java/de/neitzel/encryption/MainAlphabet.java b/encryption/src/main/java/de/neitzel/encryption/MainAlphabet.java new file mode 100644 index 0000000..10bd97d --- /dev/null +++ b/encryption/src/main/java/de/neitzel/encryption/MainAlphabet.java @@ -0,0 +1,48 @@ +package de.neitzel.encryption; + +/** + * Main characters of the Alphabet. + */ +public class MainAlphabet extends BaseAlphabet { + + /** + * All characters we want to use. + */ + private static final char[] ALL_CHARS = new char[] { + // lowercase characters + 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', + 's', 't', 'u', 'v', 'w', 'x', 'y', 'z', + + // uppercase characters + 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', + 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', + + // numbers + '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', + + // special characters + '-', '_', '?', ' ', '#', '+', '/', '*', '!', '\"', '§', '$', '%', '&', '(', ')', '=', '@', + '€', ',', ';', '.', ':', '<', '>', '|', '\'', '\\', '{', '}', '[', ']', + + // german special characters + 'ä', 'Ä', 'ö', 'Ö', 'ü', 'Ü', 'ß' + }; + + /** + * Gets the available characters. + * @return + */ + @Override + public char[] availableCharacters() { + return ALL_CHARS; + } + + /** + * Gets the radix of the alphabet. + * @return + */ + @Override + public Integer radix() { + return ALL_CHARS.length; + } +} diff --git a/encryption/src/main/java/de/neitzel/encryption/MainDomain.java b/encryption/src/main/java/de/neitzel/encryption/MainDomain.java new file mode 100644 index 0000000..573a633 --- /dev/null +++ b/encryption/src/main/java/de/neitzel/encryption/MainDomain.java @@ -0,0 +1,31 @@ +package de.neitzel.encryption; + +import com.idealista.fpe.config.Alphabet; +import com.idealista.fpe.config.Domain; +import com.idealista.fpe.config.GenericTransformations; + +public class MainDomain implements Domain { + + private Alphabet _alphabet; + private GenericTransformations transformations; + + public MainDomain() { + _alphabet = new MainAlphabet(); + transformations = new GenericTransformations(_alphabet.availableCharacters()); + } + + @Override + public Alphabet alphabet() { + return _alphabet; + } + + @Override + public int[] transform(String data) { + return transformations.transform(data); + } + + @Override + public String transform(int[] data) { + return transformations.transform(data); + } +} diff --git a/fx/pom.xml b/fx/pom.xml index 3cedb45..4b75252 100644 --- a/fx/pom.xml +++ b/fx/pom.xml @@ -21,15 +21,33 @@ + + + org.openjfx + javafx-base + + + org.openjfx + javafx-controls + + + org.openjfx + javafx-graphics + + + org.openjfx + javafx-fxml + + + org.openjfx + javafx-web + + + de.neitzel.lib core - 1.0-SNAPSHOT - - - org.reflections - reflections - ${reflections.version} + ${project.version} diff --git a/net/pom.xml b/net/pom.xml new file mode 100644 index 0000000..e10a284 --- /dev/null +++ b/net/pom.xml @@ -0,0 +1,49 @@ + + + 4.0.0 + + + de.neitzel.lib + neitzellib + 1.0-SNAPSHOT + + + net + + + + ${project.artifactId} + ${project.artifactId} + ${project.artifactId} + ${project.artifactId}-${project.version} + + + 1.6.2 + + + + + com.sun.mail + javax.mail + ${javax.mail.version} + + + + + ${jar.filename} + + + + com.github.spotbugs + spotbugs-maven-plugin + + + + org.apache.maven.plugins + maven-pmd-plugin + + + + diff --git a/net/src/main/java/de/neitzel/net/imap/ImapAccount.java b/net/src/main/java/de/neitzel/net/imap/ImapAccount.java new file mode 100644 index 0000000..cc28ef0 --- /dev/null +++ b/net/src/main/java/de/neitzel/net/imap/ImapAccount.java @@ -0,0 +1,128 @@ +package de.neitzel.net.imap; + +import java.util.Objects; + +/** + * Represents an IMAP account with server configuration, user credentials, and protocol details. + * This class provides methods to set or get the account details and overrides methods for string + * representation, equality checks, and hashing. + */ +public class ImapAccount { + + /** + * Specifies the server address for the IMAP account. + * This typically represents the hostname or IP address + * of the mail server that handles IMAP communication. + */ + protected String server; + /** + * Retrieves the server address associated with this IMAP*/ + public String getServer() { return server; } + /** + * Sets the server address for the IMAP account. + * + * @param server the server address to be configured for the IMAP account + */ + public void setServer(String server) { this.server = server; } + + /** + * Represents the username or identifier used to authenticate the IMAP account. + * This value is associated with the user's credentials required to log in + * to the IMAP server. + */ + protected String user; + /** + * Retrieves the username associated with this IMAP account. + * + * @return the username of the IMAP account as a String. + */ + public String getUser() { return user; } + /** + * Sets the username associated with the IMAP account. + * + * @param user The username to be set for this IMAP account. + */ + public void setUser(String user) { this.user = user; } + + /** + * The password associated with the IMAP account. + * This is used to authenticate the user when connecting to the IMAP server. + */ + protected String password; + /** + * Retrieves the password associated with this IMAP account. + * + * @return the password of the IMAP account. + */ + public String getPassword() { return password; } + /** + * Sets the password for the IMAP account. + * + * @param password The password to be set for the account. + */ + public void setPassword(String password) { this.password = password; } + + /** + * Specifies the protocol used for the IMAP account, such as "IMAP" or "IMAPS". + * This field determines the communication protocol for interacting with the server. + */ + protected String protocol; + /** + * Retrieves the protocol used by this IMAP account. + * + * @return the protocol as a String, which defines the communication method for the IMAP account. + */ + public String getProtocol() { return protocol; } + /** + * Sets the protocol used by the IMAP account. + * @param protocol the protocol to be used, e.g., "IMAP" or "IMAPS". + */ + public void setProtocol(String protocol) { this.protocol = protocol; } + + /** + * Provides a string representation of the ImapAccount object including its server, user, + * a masked password, and protocol information. The password is represented as '########' if it is not empty. + * + * @return A formatted string that describes the ImapAccount object with its server, user, masked password, and protocol. + */ + @Override public String toString() { + return String.format("ImapAccount(%s, %s, %s, %s", + server, + user, + password.length()==0 ? "''" : "########" , + protocol); + } + + /** + * Computes the hash code for this instance of the ImapAccount class. + * The hash code is based on the values of the server, user, password, and protocol fields. + * This ensures that instances with the same field values produce the same hash code. + * + * @return An integer hash code representing this ImapAccount instance. + */ + @Override public int hashCode() { + return Objects.hash(server, user, password, protocol); + } + + /** + * Compares this ImapAccount instance with the specified object for equality. + * The comparison is based on the equality of all relevant fields: server, user, password, and protocol. + * + * @param obj the object to compare with this instance + * @return true if the specified object is equal to this ImapAccount instance; false otherwise + */ + @Override public boolean equals(Object obj) { + // Check type of argument, includes check of null. + if (!(obj instanceof ImapAccount)) return false; + + // Check Reference equals + if (this == obj) return true; + + // Check the comparison of all field + ImapAccount other = (ImapAccount) obj; + return (server == other.server || (server != null && server.equals(other.server))) && + (user == other.user || (user != null && user.equals(other.user))) && + (password == other.password || (password != null && password.equals(other.password))) && + (protocol == other.protocol || (protocol != null && protocol.equals(other.protocol))); + } +} diff --git a/net/src/main/java/de/neitzel/net/imap/ImapAccountMonitor.java b/net/src/main/java/de/neitzel/net/imap/ImapAccountMonitor.java new file mode 100644 index 0000000..c1e0fc7 --- /dev/null +++ b/net/src/main/java/de/neitzel/net/imap/ImapAccountMonitor.java @@ -0,0 +1,256 @@ +package de.neitzel.net.imap; + +import lombok.extern.slf4j.Slf4j; + +import javax.mail.*; +import java.util.*; + +/** + * The ImapAccountMonitor class is responsible for monitoring an IMAP email account + * by maintaining a connection to the server, tracking specific folders, and + * listening for new emails. This class allows managing the set of monitored folders, + * processing unseen and undeleted messages, and notifying registered listeners when + * new messages are received. + */ +@Slf4j +public class ImapAccountMonitor { + /** + * Represents an instance of an IMAP account, encapsulating details about + * server configuration, user credentials, and protocol settings. + * This variable is used to connect and authenticate the application's interaction + * with an IMAP email server. + */ + protected ImapAccount account; + + /** + * Represents the current session for interaction with an IMAP server. + * The session encapsulates the configuration and context required + * to establish a connection and perform operations on the IMAP server. + * It is initialized and utilized internally within the application. + */ + protected Session session; + + /** + * Represents the mail store associated with the IMAP account. + * The store is used to interact with the IMAP server for email retrieval and management. + */ + protected Store store; + + /** + * Represents a collection of folders associated with an IMAP account. + * The map's keys are folder names (String), and the values are Folder objects. + * This variable is used to store and manage the hierarchy or collection + * of email folders for an IMAP account. + */ + protected Map folders = new HashMap(); + + /** + * Monitors an IMAP account by establishing a connection to the specified mail server + * using the provided account credentials and protocol. + * + * @param account the IMAP account containing details such as server, user, password, and protocol + * @throws NoSuchProviderException if the specified mail store protocol is not available + * @throws MessagingException if the connection to the mail server fails + */ + public ImapAccountMonitor(ImapAccount account) throws NoSuchProviderException, MessagingException { + log.trace("Constructor ({})", account.toString()); + this.account = account; + + Properties props = System.getProperties(); + props.setProperty("mail.store.protocol", account.getProtocol()); + session = Session.getDefaultInstance(props); + try { + store = session.getStore("imaps"); + store.connect(account.server, account.user, account.password); + } catch (NoSuchProviderException ex) { + log.error("Unable to get imaps Store.", ex); + throw ex; + } catch (MessagingException ex) { + log.error("Unable to connect.", ex); + throw ex; + } + + log.trace("Constructor done."); + } + + /** + * Closes the resources associated with the current instance, including + * IMAP folders and the store. The method ensures that all folders are + * closed properly, followed by the closure of the store. + * + * Any exceptions encountered during the closure of folders or the store + * are caught and logged without interrupting the overall closing process. + * This is to ensure that all resources are attempted to be closed even if + * an error occurs with one of them. + * + * The method logs the start and end of the closing process for traceability. + */ + public void close() { + log.trace("close() called."); + + // Close the folders + for (Folder folder: folders.values()) { + try { + folder.close(false); + } catch (MessagingException ex) { + // Only log the exception. + log.warn("Exception when closing folder.", ex); + } + } + + // Close the store + try { + store.close(); + } catch (MessagingException ex) { + // Only log the error. + log.warn("Exception when closing the store.", ex); + } + + log.trace("close() call ended."); + } + + /** + * Adds a new folder to the IMAP account and opens it in read-write mode. + * The folder is added to an internal collection for future access. + * + * @param name the name of the folder to be added and opened + * @throws MessagingException if any error occurs while accessing or opening the folder + */ + public void addFolder(String name) throws MessagingException { + log.trace("addFolder(%s) called.", name); + Folder folder = store.getFolder(name); + folder.open(Folder.READ_WRITE); + folders.put(name, folder); + log.trace("addFolder({}) call ended.", name); + } + + /** + * Removes the folder with the specified name from the account's folder list. + * If the folder is not found, the method does nothing. + * After removing the folder, it attempts to close any associated resources. + * + * @param name the name of the folder to be removed + */ + public void removeFolder(String name) { + log.trace("removeFolder({}) called.", name); + + // Validate folder is known. + if (!folders.containsKey(name)) return; + + Folder folder = folders.get(name); + folders.remove(name); + try { + folder.close(false); + } catch (MessagingException ex) { + // TODO: Handle exception ... + } + + log.trace("removeFolder({}) call ended.", name); + } + + /** + * Checks all monitored folders for new email messages, processes unseen and undeleted messages, + * and raises a NewMailEvent for each new email discovered. The method ensures processed messages + * are marked as seen. + * + * The method iterates through all folders currently being monitored, fetching their messages and + * evaluating the state of each. If a message is neither marked as seen nor deleted, it is marked + * as seen and a NewMailEvent is raised for it. + * + * Proper error handling is implemented to log any MessagingException that occurs while processing + * the messages of a folder without interrupting the processing of other folders. + * + * Note: This method relies on external logging (via `log`) and appropriate event handling + * via `raiseNewEmailEvent`. The `folders` collection holds the monitored folders required. + * + * The folder processing stops only in case of irrecoverable exceptions outside this method's scope. + */ + public void check() { + log.trace("check() called."); + + // Loop through all folders that are monitored + for (Folder folder: folders.values()) { + try { + // Loop through all messages. + Message[] messages = folder.getMessages(); + for (Message message: messages) { + // Check if message wasn't seen and wasn't deleted + if (!message.isSet(Flags.Flag.SEEN) && !message.isSet(Flags.Flag.DELETED)) { + // Mark message as seen. + message.setFlag(Flags.Flag.SEEN, true); + + // Raise NewMailEvent + raiseNewEmailEvent(message); + } + } + } catch (MessagingException ex) { + log.error("Exception when reading messages of folder {}.", folder.getName(), ex); + // So far no handling of this error except logging it. + } + } + + log.trace("check() call ended."); + } + + /** + * A collection of listeners that respond to IMAP-related events. + * Each listener in this collection can perform specific actions when triggered + * by events such as receiving new email notifications. + */ + private Collection imapListeners = new ArrayList(); + + /** + * Adds an IMAP listener to receive notifications about IMAP-related events such as new email arrivals. + * + * @param listener the ImapListener instance to be added to the list of listeners + */ + public void addImapListener(ImapListener listener) { + log.trace("addImapListener() called!"); + imapListeners.add(listener); + } + + /** + * Removes the specified IMAP listener from the list of active listeners. + * If the listener is present, it will be removed; otherwise, no action is taken. + * + * @param listener The IMAP listener to be removed. + */ + public void removeImapListener(ImapListener listener) { + log.trace("removeImapListener() called!"); + if (imapListeners.contains(listener)) { + log.info("Removing the IMAP listener."); + imapListeners.remove(listener); + } + } + + /** + * Raises a new email event and notifies all registered listeners. + * The method loops through the listeners and invokes their {@code NewEmailReceived} + * method with a newly created {@link NewEmailEvent}. + * If a listener marks the event as handled, the remaining listeners will + * not be notified. + * + * @param message The email message that triggered the event. This message + * is included in the {@link NewEmailEvent} passed to the listeners. + */ + protected void raiseNewEmailEvent(Message message) { + log.trace("raiseNewEmailEvent() called!"); + + // Create the event. + NewEmailEvent event = new NewEmailEvent(this, message); + + // Call all listeners. + for (ImapListener listener: imapListeners) { + log.trace("Calling listener in {} ....", listener.getClass().getName()); + listener.newEmailReceived(event); + + // Check if the event was handled so no further ImaListeners will be called. + if (event.isHandled()) { + log.trace("raiseNewEmailEvent(): Breaking out of listener loop because event was handled."); + break; + } + } + + log.trace("raiseNewEmailEvent() call ended!"); + } +} diff --git a/net/src/main/java/de/neitzel/net/imap/ImapListener.java b/net/src/main/java/de/neitzel/net/imap/ImapListener.java new file mode 100644 index 0000000..29ab8fe --- /dev/null +++ b/net/src/main/java/de/neitzel/net/imap/ImapListener.java @@ -0,0 +1,17 @@ +package de.neitzel.net.imap; + +/** + * Listener interface for receiving notifications about new emails. + * Classes interested in processing new emails should implement this interface and + * register themselves to receive events via supported mechanisms. + */ +public interface ImapListener { + /** + * This method gets invoked when a new email is received. Implementers of this method + * handle the processing of new email events triggered by the associated source. + * + * @param event the NewEmailEvent object that contains information about the received email, + * including the email message and its source. + */ + void newEmailReceived(NewEmailEvent event); +} diff --git a/net/src/main/java/de/neitzel/net/imap/NewEmailEvent.java b/net/src/main/java/de/neitzel/net/imap/NewEmailEvent.java new file mode 100644 index 0000000..5c1c4eb --- /dev/null +++ b/net/src/main/java/de/neitzel/net/imap/NewEmailEvent.java @@ -0,0 +1,48 @@ +package de.neitzel.net.imap; + +import lombok.Getter; +import lombok.Setter; + +import javax.mail.Message; +import java.util.EventObject; + +/** + * Event class representing the occurrence of a new email. + * It is typically used to encapsulate information about the received email + * and provide a means for event listeners to handle the event. + */ +public class NewEmailEvent extends EventObject { + + /** + * Represents the email message associated with the NewEmailEvent. + * This field encapsulates the content and metadata of the email + * received, allowing event listeners to process the message details. + */ + @Getter + @Setter + protected Message message; + + /** + * Indicates whether the event has already been handled or processed. + * When true, it signifies that the event has been handled and no further + * processing is required. It is used to prevent multiple handling + * of the same event. + */ + @Getter + @Setter + protected boolean handled = false; + + /** + * Constructs a new NewEmailEvent instance. + * This event encapsulates information about a newly received email, + * including its associated message and the source of the event. + * + * @param source the object on which the event initially occurred; typically represents + * the source of the email event, such as an email client or server. + * @param message the Message object representing the email associated with this event. + */ + public NewEmailEvent(Object source, Message message) { + super(source); + this.message = message; + } +} diff --git a/net/src/main/java/de/neitzel/net/mail/MessageUtils.java b/net/src/main/java/de/neitzel/net/mail/MessageUtils.java new file mode 100644 index 0000000..bc2c15f --- /dev/null +++ b/net/src/main/java/de/neitzel/net/mail/MessageUtils.java @@ -0,0 +1,82 @@ +package de.neitzel.net.mail; + +import javax.mail.BodyPart; +import javax.mail.Message; +import javax.mail.MessagingException; +import javax.mail.internet.ContentType; +import javax.mail.internet.MimeMultipart; +import java.io.IOException; + +/** + * Utility functions to use with javax.mail.Message instances. + */ +public class MessageUtils { + /** + * Gets the text of the email message. + * @param message Message to get the text from. + * @return Text of the email message. + * @throws IOException + * @throws MessagingException + */ + public static String getTextFromMessage(Message message) throws IOException, MessagingException { + String result = ""; + if (message.isMimeType("text/plain")) { + result = message.getContent().toString(); + } else if (message.isMimeType("multipart/*")) { + MimeMultipart mimeMultipart = (MimeMultipart) message.getContent(); + result = getTextFromMimeMultipart(mimeMultipart); + } + return result; + } + + /** + * Gets the text of a MimeMultipart. + * @param mimeMultipart MimeMultipart to get the text from. + * @return Text of the MimeMultipart instance. + * @throws IOException + * @throws MessagingException + */ + private static String getTextFromMimeMultipart( + MimeMultipart mimeMultipart) throws IOException, MessagingException { + + int count = mimeMultipart.getCount(); + if (count == 0) + throw new MessagingException("Multipart with no body parts not supported."); + boolean multipartAlt = new ContentType(mimeMultipart.getContentType()).match("multipart/alternative"); + if (multipartAlt) + // alternatives appear in an order of increasing + // faithfulness to the original content. Customize as req'd. + return getTextFromBodyPart(mimeMultipart.getBodyPart(count - 1)); + String result = ""; + for (int i = 0; i < count; i++) { + BodyPart bodyPart = mimeMultipart.getBodyPart(i); + result += getTextFromBodyPart(bodyPart); + } + return result; + } + + /** + * Gets the text of a BodyPart + * @param bodyPart BodyPart to get text from. + * @return Text of body part or empty string if not a known type. + * @throws IOException + * @throws MessagingException + */ + private static String getTextFromBodyPart( + BodyPart bodyPart) throws IOException, MessagingException { + + String result = ""; + if (bodyPart.isMimeType("text/plain")) { + result = (String) bodyPart.getContent(); + } else if (bodyPart.isMimeType("text/html")) { + result = (String) bodyPart.getContent(); + //String html = (String) bodyPart.getContent(); + // Not parsing the html right now! + // result = org.jsoup.Jsoup.parse(html).text(); + } else if (bodyPart.getContent() instanceof MimeMultipart){ + result = getTextFromMimeMultipart((MimeMultipart)bodyPart.getContent()); + } + return result; + } + +} diff --git a/pom.xml b/pom.xml index 0a2648f..35ab1ba 100644 --- a/pom.xml +++ b/pom.xml @@ -12,7 +12,9 @@ core + encryption fx + net fx-example @@ -27,7 +29,7 @@ 1.18.32 5.12.0 0.10.2 - + 2.0.17 2.16.2 @@ -60,34 +62,44 @@ - - - - org.openjfx - javafx-base - ${javafx.version} - - - org.openjfx - javafx-controls - ${javafx.version} - - - org.openjfx - javafx-graphics - ${javafx.version} - - - org.openjfx - javafx-fxml - ${javafx.version} - - - org.openjfx - javafx-web - ${javafx.version} - + + + + + org.openjfx + javafx-base + ${javafx.version} + + + org.openjfx + javafx-controls + ${javafx.version} + + + org.openjfx + javafx-graphics + ${javafx.version} + + + org.openjfx + javafx-fxml + ${javafx.version} + + + org.openjfx + javafx-web + ${javafx.version} + + + + org.slf4j + slf4j-simple + ${slf4j.version} + + + + org.projectlombok @@ -96,6 +108,13 @@ provided + + + org.slf4j + slf4j-api + ${slf4j.version} + + org.junit.jupiter