ServerVersion

The ServerVersion class is a public class that implements the Comparable interface. It represents a server version and allows for comparisons between different server versions.

public int compareTo(ServerVersion o)

@Override
public int compareTo(ServerVersion o) {
    int c = major.compareTo(o.major);
    if (c == 0) {
        c = minor.compareTo(o.minor);
        if (c == 0) {
            c = patch.compareTo(o.patch);
            if (c == 0) {
                if (extra == null) {
                    c = o.extra == null ? 0 : 1;
                } else if (o.extra == null) {
                    c = -1;
                } else {
                    c = extra.compareTo(o.extra);
                }
            }
        }
    }
    return c;
}

The compareTo method in the ServerVersion class is used to compare two ServerVersion objects based on their properties such as major version, minor version, patch version, and extra information.

Here is a step-by-step description of what the compareTo method does:

1. Compares the major property of the current ServerVersion object to the major property of the o object (passed as an argument to the method) using the compareTo method. The result is stored in the variable c.
2. If c is equal to 0 (indicating that the major versions are equal), the method proceeds to compare the minor property of both objects using the compareTo method. The result is again stored in the variable c.
3. If c is equal to 0 (indicating that the minor versions are equal), the method compares the patch property of both objects using the compareTo method. The result is again stored in the variable c.
4. If c is equal to 0 (indicating that the patch versions are equal), the method checks if the extra property of the current object is null. If it is null, the method checks if the extra property of the o object is also null. If both are null, the method sets c to 0. Otherwise, it sets c to 1.
5. If c is not equal to 0 (indicating that the extra strings are different), the method checks if the o.extra property is null. If it is null, the method sets c to -1. Otherwise, it proceeds to compare the extra property of both objects using the compareTo method.
6. Finally, the method returns the value of c, which represents the result of the comparison.

In summary, the compareTo method compares two ServerVersion objects based on their major, minor, patch versions, and extra information. It returns 0 if the objects are equal, a positive integer if the current object is greater than the argument object, and a negative integer if the current object is less than the argument object.

The compareTo method in the ServerVersion class is used to compare two ServerVersion objects. It compares the major, minor, and patch versions of the two objects sequentially.

The method first compares the major versions of the two objects using the compareTo method of the major version. If the major versions are equal, it moves on to compare the minor versions. If the minor versions are also equal, it compares the patch versions.

If the patch versions are equal as well, it checks if the extra field of one object is null. If the extra field is null, it considers the other object as greater (returns 1). If the extra field of the other object is null, it considers the current object as greater (returns -1). If both extra fields are not null, it compares them using the compareTo method of the extra field.

Finally, the method returns the value of c, which represents the comparison result. A negative value indicates that the current object is less than the given object, a positive value indicates it is greater, and a zero value indicates they are equal.

Status

The Status class is a public class that represents the status of a certain process or entity. Its primary purpose is to provide information about the current state or condition of the process or entity it represents. With its various methods and attributes, the Status class allows software engineers to easily track and manage the status of different processes within their applications.

private static int extractCode(Token codeToken) {
    try {
        return Integer.parseInt(codeToken.getValue());
    } catch (Exception e) {
        throw new IllegalArgumentException(NatsConstants.INVALID_HEADER_STATUS_CODE);
    }
}

The extractCode method is used to extract an integer value from a Token object. The method takes a single parameter codeToken, which represents the token containing the code value.

Here is a step-by-step description of what the extractCode method is doing based on its body:

1. The method is declared as private and static, indicating that it can only be accessed within the io.nats.client.support.Status class and does not require an instance of the class to be called.

2. The method signature specifies that the return type of the method is int, indicating that the method will return an integer value.

3. Within a try block, the method attempts to parse the value of the codeToken by calling the getValue method on it, and then converting the returned value to an integer using the Integer.parseInt method.

4. If the parsing succeeds, the parsed integer value is returned as the result of the method.

5. If an exception occurs during parsing, for example, if the value of the codeToken is not a valid integer, the method catches the exception.

6. In the catch block, an IllegalArgumentException is thrown with the message NatsConstants.INVALID_HEADER_STATUS_CODE. This indicates that the code value could not be extracted due to an invalid format.

That's a step-by-step description of the extractCode method in the io.nats.client.support.Status class.

The method extractCode is a private static method defined in the class io.nats.client.support.Status.

It takes a parameter codeToken of type Token and returns an integer.

The purpose of this method is to extract the code value from the codeToken and convert it into an integer.

If an exception occurs during the conversion process, it throws an IllegalArgumentException with the message "Invalid header status code defined in NatsConstants class".

JwtUtils

The JwtUtils class is an abstract class that implements ADR-14.

public static String issueUserJWT(NKey signingKey, String publicUserKey, String name, Duration expiration, long issuedAt, UserClaim nats) throws GeneralSecurityException, IOException {
    // Validate the signingKey:
    if (signingKey.getType() != NKey.Type.ACCOUNT) {
        throw new IllegalArgumentException("issueUserJWT requires an account key for the signingKey parameter, but got " + signingKey.getType());
    }
    // Validate the accountId:
    NKey accountKey = NKey.fromPublicKey(nats.issuerAccount.toCharArray());
    if (accountKey.getType() != NKey.Type.ACCOUNT) {
        throw new IllegalArgumentException("issueUserJWT requires an account key for the accountId parameter, but got " + accountKey.getType());
    }
    // Validate the publicUserKey:
    NKey userKey = NKey.fromPublicKey(publicUserKey.toCharArray());
    if (userKey.getType() != NKey.Type.USER) {
        throw new IllegalArgumentException("issueUserJWT requires a user key for the publicUserKey, but got " + userKey.getType());
    }
    String accSigningKeyPub = new String(signingKey.getPublicKey());
    String claimName = Validator.nullOrEmpty(name) ? publicUserKey : name;
    return issueJWT(signingKey, publicUserKey, claimName, expiration, issuedAt, accSigningKeyPub, nats);
}

The issueUserJWT method is defined as follows:

public static String issueUserJWT(NKey signingKey, String publicUserKey, String name, Duration expiration, long issuedAt, UserClaim nats) throws GeneralSecurityException, IOException {
    // Validate the signingKey:
    if (signingKey.getType() != NKey.Type.ACCOUNT) {
        throw new IllegalArgumentException("issueUserJWT requires an account key for the signingKey parameter, but got " + signingKey.getType());
    }
    // Validate the accountId:
    NKey accountKey = NKey.fromPublicKey(nats.issuerAccount.toCharArray());
    if (accountKey.getType() != NKey.Type.ACCOUNT) {
        throw new IllegalArgumentException("issueUserJWT requires an account key for the accountId parameter, but got " + accountKey.getType());
    }
    // Validate the publicUserKey:
    NKey userKey = NKey.fromPublicKey(publicUserKey.toCharArray());
    if (userKey.getType() != NKey.Type.USER) {
        throw new IllegalArgumentException("issueUserJWT requires a user key for the publicUserKey, but got " + userKey.getType());
    }
    String accSigningKeyPub = new String(signingKey.getPublicKey());
    String claimName = Validator.nullOrEmpty(name) ? publicUserKey : name;
    return issueJWT(signingKey, publicUserKey, claimName, expiration, issuedAt, accSigningKeyPub, nats);
}

The steps carried out by this method, based on its body, are as follows:

1. Validate the signingKey parameter to ensure that it is of type NKey.Type.ACCOUNT. If it is not, throw an IllegalArgumentException with a message indicating the incorrect type.

2. Validate the accountId parameter by converting it to an NKey object using NKey.fromPublicKey. Ensure that the resulting key has a type of NKey.Type.ACCOUNT. If it does not, throw an IllegalArgumentException with a message indicating the incorrect type.

3. Validate the publicUserKey parameter by converting it to an NKey object using NKey.fromPublicKey. Ensure that the resulting key has a type of NKey.Type.USER. If it does not, throw an IllegalArgumentException with a message indicating the incorrect type.

4. Convert the signingKey's public key to a String using new String(signingKey.getPublicKey()).

5. Set the claimName variable based on the value of the name parameter. If the name parameter is null or empty, use the value of publicUserKey as the claimName.

6. Call the issueJWT method, passing in the signingKey, publicUserKey, claimName, expiration, issuedAt, accSigningKeyPub, and nats parameters.

7. Return the result of the issueJWT method as the output of the issueUserJWT method.

Note: The issueJWT method is not included in the provided code snippet.

The issueUserJWT method in the JwtUtils class is responsible for generating a JSON Web Token (JWT) for a user.

Here's a breakdown of what the method does:

1. It first validates the signingKey parameter to ensure that it is of type NKey.Type.ACCOUNT. If not, it throws an IllegalArgumentException.

2. It then validates the accountId parameter by converting it to an NKey object and checking if it is of type NKey.Type.ACCOUNT. If not, it throws an IllegalArgumentException.

3. Next, it validates the publicUserKey parameter by converting it to an NKey object and checking if it is of type NKey.Type.USER. If not, it throws an IllegalArgumentException.

4. The method then generates the public key of the signing key as a string.

5. It determines the claimName for the JWT by checking if the name parameter is null or empty. If so, it uses the publicUserKey as the claim name, otherwise it uses the name parameter.

6. Finally, it calls the issueJWT method, passing in the necessary parameters, to issue the JWT and returns the generated token.

Note: The method may throw GeneralSecurityException or IOException if there are any issues during the JWT generation process.

public static String issueJWT(NKey signingKey, String publicUserKey, String name, Duration expiration, long issuedAt, String accSigningKeyPub, JsonSerializable nats) throws GeneralSecurityException, IOException {
    Claim claim = new Claim();
    claim.exp = expiration;
    claim.iat = issuedAt;
    claim.iss = accSigningKeyPub;
    claim.name = name;
    claim.sub = publicUserKey;
    claim.nats = nats;
    // Issue At time is stored in unix seconds
    String claimJson = claim.toJson();
    // Compute jti, a base32 encoded sha256 hash
    MessageDigest sha256 = MessageDigest.getInstance("SHA-256");
    byte[] encoded = sha256.digest(claimJson.getBytes(StandardCharsets.UTF_8));
    claim.jti = new String(base32Encode(encoded));
    claimJson = claim.toJson();
    // all three components (header/body/signature) are base64url encoded
    String encBody = toBase64Url(claimJson);
    // compute the signature off of header + body (. included on purpose)
    byte[] sig = (ENCODED_CLAIM_HEADER + "." + encBody).getBytes(StandardCharsets.UTF_8);
    String encSig = toBase64Url(signingKey.sign(sig));
    // append signature to header and body and return it
    return ENCODED_CLAIM_HEADER + "." + encBody + "." + encSig;
}

The issueJWT method, defined in the io.nats.client.support.JwtUtils class, is responsible for issuing a JSON Web Token (JWT) based on the provided parameters.

public static String issueJWT(NKey signingKey, String publicUserKey, String name, Duration expiration, long issuedAt, String accSigningKeyPub, JsonSerializable nats) throws GeneralSecurityException, IOException

• signingKey: NKey object representing the private key used for signing the JWT.
• publicUserKey: String representing the public key of the user.
• name: String representing the name associated with the JWT.
• expiration: Duration object representing the time duration for which the JWT is valid.
• issuedAt: long representing the timestamp when the JWT was issued.
• accSigningKeyPub: String representing the public key of the account signing key.
• nats: JsonSerializable object representing additional data associated with the JWT.

The method returns a String representing the issued JWT.

The issueJWT method follows the following steps to issue the JWT:

1. Create a new Claim object.
2. Set the expiration, issuedAt, accSigningKeyPub, name, publicUserKey, and nats fields of the Claim object based on the provided parameters.
3. Convert the Claim object to a JSON string using the toJson method and store it in the claimJson variable.
4. Compute the SHA-256 hash of the claimJson string and encode it using base32 encoding. Set the result as the jti field of the Claim object.
5. Convert the Claim object to JSON string again and update the claimJson variable with the updated JSON string.
6. Encode the claimJson string using base64url encoding and store it in the encBody variable.
7. Concatenate the ENCODED_CLAIM_HEADER, ".", and encBody and convert it to bytes using UTF-8 encoding. Store the result in the sig variable.
8. Sign the sig bytes using the signingKey and encode the resulting signature using base64url encoding. Store the result in the encSig variable.
9. Concatenate the ENCODED_CLAIM_HEADER, ".", encBody, ".", and encSig to form the final JWT.
10. Return the final JWT.

Note: The values of ENCODED_CLAIM_HEADER and base32Encode methods are not provided in the given code snippet.

The issueJWT method in the JwtUtils class is responsible for generating a JSON Web Token (JWT) using the provided input parameters.

Here's a breakdown of what the method does:

1. The method takes in a signingKey, publicUserKey, name, expiration, issuedAt, accSigningKeyPub, and nats parameter. These parameters are used to create the claims for the JWT.

2. A new Claim object is created and the input parameters are assigned to the respective claim fields.

3. The claimJson is generated by converting the Claim object to JSON.

4. The jti claim field is computed by creating a SHA-256 hash of the claimJson and encoding it in base32.

5. The claimJson is converted to base64url encoding.

6. The signature (encSig) is computed by signing the concatenation of the encoded claim header, encoded claim body, and a dot delimiter using the signingKey.

7. The JWT is constructed by concatenating the encoded claim header, encoded claim body, and encoded signature with dot delimiters.

8. Finally, the generated JWT is returned.

This method is used to issue a JWT with the provided claims and is typically used for authentication and authorization purposes in a distributed system.

NatsJetStreamClientError

The NatsJetStreamClientError class is a public class that represents an error that can occur when using the NATS JetStream client. This class is used to handle and manage error conditions specific to the JetStream functionality of the NATS messaging system.

private RuntimeException _instance(String msg) {
    if (kind == KIND_ILLEGAL_ARGUMENT) {
        return new IllegalArgumentException(msg);
    }
    return new IllegalStateException(msg);
}

The _instance method defined in the NatsJetStreamClientError class in the io.nats.client.support package is responsible for creating and returning a RuntimeException based on the provided message.

Here is a step-by-step description of what the _instance method does:

1. The method takes a single parameter msg, which represents the error message that will be included in the created exception object.

2. The method first checks the value of the kind variable.

3. If the value of kind is KIND_ILLEGAL_ARGUMENT, the method creates a new IllegalArgumentException instance with the provided msg as the error message.

4. If the value of kind is not KIND_ILLEGAL_ARGUMENT, the method creates a new IllegalStateException instance with the provided msg as the error message.

5. The created exception object is then returned by the method.

Note: The exact implementation of KIND_ILLEGAL_ARGUMENT and the declaration of kind are not shown in the provided code snippet, so the behavior of the method may vary depending on the actual values and logic in the code.

The _instance method, defined in the NatsJetStreamClientError class of the io.nats.client.support package, is a private method that returns a RuntimeException based on the given message parameter.

If the kind variable is equal to KIND_ILLEGAL_ARGUMENT, it creates and returns an IllegalArgumentException with the given message. Otherwise, it creates and returns an IllegalStateException with the given message.

JsonValue

The JsonValue class is a public class in Java that implements the JsonSerializable interface. It represents a value in JSON format and provides methods to serialize and deserialize JSON objects. This class is commonly used in software engineering for handling JSON data in applications.

public String toJson()

@Override
public String toJson() {
    switch(type) {
        case STRING:
            return valueString(string);
        case BOOL:
            return valueString(bool);
        case MAP:
            return valueString(map);
        case ARRAY:
            return valueString(array);
        case INTEGER:
            return i.toString();
        case LONG:
            return l.toString();
        case DOUBLE:
            return d.toString();
        case FLOAT:
            return f.toString();
        case BIG_DECIMAL:
            return bd.toString();
        case BIG_INTEGER:
            return bi.toString();
        default:
            return NULL_STR;
    }
}

The toJson() method in the JsonValue class, defined in the io.nats.client.support package, converts the value of an object to its respective JSON representation. It does this by switching on the type of the object, and returning the JSON representation based on the type.

Here is a step-by-step breakdown of what the toJson() method does:

1. Start of the method toJson().
2. Switch on the type of the object.
3. If the type is STRING, return the JSON representation of the string value using the helper method valueString(string).
4. If the type is BOOL, return the JSON representation of the bool value using the helper method valueString(bool).
5. If the type is MAP, return the JSON representation of the map value using the helper method valueString(map).
6. If the type is ARRAY, return the JSON representation of the array value using the helper method valueString(array).
7. If the type is INTEGER, return the toString() representation of the i value.
8. If the type is LONG, return the toString() representation of the l value.
9. If the type is DOUBLE, return the toString() representation of the d value.
10. If the type is FLOAT, return the toString() representation of the f value.
11. If the type is BIG_DECIMAL, return the toString() representation of the bd value.
12. If the type is BIG_INTEGER, return the toString() representation of the bi value.
13. If none of the above cases match, return the string representation of NULL_STR.
14. End of the toJson() method.

Note that the valueString() helper method is used for converting certain types such as string, bool, map, and array to their respective JSON representations.

This is a high-level overview of what the toJson() method in the JsonValue class does based on its body. The exact functionality and behavior may depend on the implementation and usage of the JsonValue class and its dependencies.

The toJson method in the JsonValue class is used to convert the current instance of JsonValue into a JSON string representation.

Based on the implementation, the method performs a switch statement on the type of the JsonValue. Depending on the type, it returns the JSON representation of the corresponding value.

If the type is STRING, it returns the JSON representation of the string value. If the type is BOOL, it returns the JSON representation of the bool value. If the type is MAP, it returns the JSON representation of the map value. If the type is ARRAY, it returns the JSON representation of the array value.

If the type is INTEGER, LONG, DOUBLE, FLOAT, BIG_DECIMAL, or BIG_INTEGER, it returns the string representation of the respective value.

If none of the above cases match, it returns the JSON representation of null.

private String valueString(Map<String, JsonValue> map) {
    StringBuilder sbo = beginJson();
    for (String key : map.keySet()) {
        addField(sbo, key, map.get(key));
    }
    return endJson(sbo).toString();
}

The valueString method in the JsonValue class is used to convert a given map of key-value pairs into a JSON string. Here is a step-by-step description of what this method does:

1. Declare a StringBuilder object named sbo and initialize it by calling the beginJson method. This method is not defined in the given code snippet, so its implementation details are not known.

2. Iterate over the keys of the map using a for-each loop. For each key, do the following:

   a. Call the addField method, passing in the sbo string builder, the current key, and the corresponding value from the map. The addField method is not defined in the given code snippet, so its implementation details are not known.

3. After the iteration is complete, call the endJson method, passing in the sbo string builder. This method is not defined in the given code snippet, so its implementation details are not known. The method should finalize the creation of the JSON string.

4. Convert the sbo string builder to a string by calling the toString method.

5. Return the JSON string.

Please note that without the implementation details of the beginJson, addField, and endJson methods, it is not possible to fully determine the behavior of the valueString method.

The valueString method is a private method defined in the JsonValue class within the io.nats.client.support package. It takes in a Map of type String and JsonValue as input.

The method loops through the keys of the map and for each key, it calls the addField method and passes the sbo (a StringBuilder) and the corresponding value associated with the key in the map. The addField method is responsible for appending the formatted JSON field to the sbo builder.

After iterating through all the keys in the map, the method calls the endJson method and passes the sbo builder to generate the closing part of the JSON string. The endJson method returns a StringBuilder with the complete JSON string.

Finally, the method converts the StringBuilder to a String by calling the toString method and returns the result.

private String valueString(List<JsonValue> list) {
    StringBuilder sba = beginArray();
    for (JsonValue v : list) {
        sba.append(v.toJson());
        sba.append(COMMA);
    }
    return endArray(sba).toString();
}

The valueString method, defined in the JsonValue class in the io.nats.client.support package, takes a list of JsonValue objects as its parameter.

Here is a step-by-step description of what the valueString method does based on its body:

1. The method starts by creating a StringBuilder object named sba by calling the beginArray method. The beginArray method is not shown in the provided code snippet, but it is assumed to initialize the StringBuilder with an opening array bracket "[".

2. The method then enters a loop that iterates over each JsonValue object in the list parameter.

3. Inside the loop, the toJson method is called on each JsonValue object v. The toJson method converts the JsonValue object into its string representation.

4. The resulting string is appended to the sba StringBuilder object by calling the append method.

5. After appending the string representation of the JsonValue object, a comma (,) is also appended to the sba StringBuilder object by calling the append method with the COMMA constant.

6. Steps 4 and 5 are repeated for each JsonValue object in the list parameter.

7. Once the loop iteration is complete, the sba StringBuilder object is passed to the endArray method. The endArray method is not shown in the provided code snippet, but it is assumed to append the closing array bracket "]" to the StringBuilder and perform any necessary post-processing.

8. The endArray method returns the sba StringBuilder object as a String by calling the toString method.

9. Finally, the valueString method returns the String representation of the StringBuilder object.

In summary, the valueString method takes a list of JsonValue objects, converts each object into its string representation, and combines them with commas to form a JSON array. The resulting JSON array string is returned as the output of the method.

The valueString method in the io.nats.client.support.JsonValue class is used to convert a list of JsonValue objects into a string representation.

It takes a List<JsonValue> as input and iterates through the elements of the list. For each JsonValue element, it appends the result of calling its toJson() method to a StringBuilder, followed by a comma.

Finally, it calls the endArray method, passing the StringBuilder as a parameter, and converts the result to a string by calling toString().

The purpose of this method is to generate a string representation of the given list of JsonValue objects, suitable for JSON serialization or other similar purposes.

Validator

The Validator class is an abstract class that provides a framework for implementing various validation logic in a software application. It serves as a base class for creating specific validator classes that can be used to validate different types of data or entities.

public static String validateSubject(String subject, String label, boolean required, boolean cantEndWithGt) {
    if (emptyAsNull(subject) == null) {
        if (required) {
            throw new IllegalArgumentException(label + " cannot be null or empty.");
        }
        return null;
    }
    String[] segments = subject.split("\\.");
    for (int x = 0; x < segments.length; x++) {
        String segment = segments[x];
        if (segment.equals(">")) {
            if (cantEndWithGt || x != segments.length - 1) {
                // if it can end with gt, gt must be last segment
                throw new IllegalArgumentException(label + " cannot contain '>'");
            }
        } else if (!segment.equals("*") && notPrintable(segment)) {
            throw new IllegalArgumentException(label + " must be printable characters only.");
        }
    }
    return subject;
}

The validateSubject method in class io.nats.client.support.Validator is used to validate a subject string based on certain criteria. Here is a step-by-step description of what the method does:

1. The method takes four parameters: subject (the subject string to validate), label (a label used in error messages), required (a boolean flag indicating if the subject is required), and cantEndWithGt (a boolean flag indicating if the subject cannot end with '>').

2. The method first checks if the subject is null or empty by calling the emptyAsNull helper method. If the subject is null or empty and is marked as required, an IllegalArgumentException is thrown with an error message stating that the label cannot be null or empty. If the subject is not required and is null or empty, the method returns null.

3. If the subject is not null or empty, the method splits the subject into segments using the dot ('.') as the delimiter. Each segment represents a part of the subject string.

4. The method then iterates over each segment in the segments array.

5. For each segment, the method checks if it is equal to '>'. If it is, two conditions are checked: (a) if cantEndWithGt is true or if the segment is not the last segment in the subject. If either of these conditions is true, an IllegalArgumentException is thrown with an error message stating that the label cannot contain '>'. This check is to ensure that if the subject is not allowed to end with '>', it must be the last segment.

6. If the segment is not equal to '>', the method checks if it is equal to '' or if it contains any non-printable characters. The notPrintable helper method is used to determine if a segment contains any non-printable characters. If the segment is neither '' nor consists of only printable characters, an IllegalArgumentException is thrown with an error message stating that the label must be printable characters only.

7. If all segments pass the validation checks, the method returns the original subject string.

Overall, the validateSubject method ensures that the provided subject string meets the specified criteria, such as not being null or empty, not containing '>', and consisting of only printable characters. If any of the validation conditions fail, an IllegalArgumentException is thrown.

The validateSubject method in the Validator class is used to validate a subject string. It takes four parameters: subject, label, required, and cantEndWithGt.

The method first checks if the subject string is null or empty. If it is and the required parameter is true, it throws an IllegalArgumentException with a message indicating that the subject cannot be null or empty. If the subject is null or empty and the required parameter is false, it returns null.

Next, the method splits the subject string into segments using the dot (".") as the separator. It then iterates over each segment and performs validation checks.

If a segment equals ">", the method checks if cantEndWithGt is true or if it is the last segment in the subject. If either condition is true, it throws an IllegalArgumentException with a message indicating that the subject cannot contain ">", as it violates the validation rule.

If a segment is neither "*" nor printable, the method throws an IllegalArgumentException with a message indicating that the subject must consist of printable characters only.

Finally, if all validation checks pass, the method returns the subject string.

public static String validatePrefixOrDomain(String s, String label, boolean required) {
    return _validate(s, required, label, () -> {
        if (s.startsWith(DOT)) {
            throw new IllegalArgumentException(label + " cannot start with `.` [" + s + "]");
        }
        if (notPrintableOrHasWildGt(s)) {
            throw new IllegalArgumentException(label + " must be in the printable ASCII range and cannot include `*`, `>` [" + s + "]");
        }
        return s;
    });
}

The validatePrefixOrDomain method, defined in the io.nats.client.support.Validator class, is used to validate a given string s as either a prefix or domain. It takes three parameters: s (the string to be validated), label (the label used in error messages), and required (a boolean indicating whether the string is required or not).

Here is the step-by-step description of what the validatePrefixOrDomain method does based on its body:

1. Call the private method _validate with the parameters s, required, label, and a lambda expression. This lambda expression contains the validation logic for the string.

2. In the lambda expression:

   • Check if the string s starts with a dot (.). If it does, throw an IllegalArgumentException with an error message indicating that the label cannot start with a dot.
   • Check if the string s is not printable ASCII or if it contains the characters * or >. If it does, throw an IllegalArgumentException with an error message indicating that the label must be in the printable ASCII range and cannot include * or >.
   • If the string passes the above checks, return the string s.

3. Return the string s from the validatePrefixOrDomain method.

Note: The _validate method is not described in the provided code snippet, but it can be inferred that it performs common validation logic and error handling.

The validatePrefixOrDomain method is used to validate a prefix or domain string.

The method takes three parameters: s which is the string to be validated, label which is a label to describe the string being validated, and required which is a boolean value indicating if the string is required or not.

Inside the method, the _validate function is called with the string, required flag, and label as arguments. This function performs the actual validation.

The validation checks for two conditions. First, it checks if the string starts with a dot (.). If it does, it throws an IllegalArgumentException with a message indicating that the string cannot start with a dot.

Second, it checks if the string is not printable ASCII or contains wildcard characters (* or >). If either of these conditions is true, it throws an IllegalArgumentException with a message indicating that the string must be in the printable ASCII range and cannot contain wildcard characters.

If both checks pass, the method returns the validated string.

In summary, the validatePrefixOrDomain method ensures that a given prefix or domain string meets certain criteria: it does not start with a dot and it is printable ASCII without wildcard characters.

public static String validateMustMatchIfBothSupplied(String s1, String s2, NatsJetStreamClientError err) {
    // s1   | s2   || result
    // ---- | ---- || --------------
    // null | null || valid, null s2
    // null | y    || valid, y s2
    // x    | null || valid, x s1
    // x    | x    || valid, x s1
    // x    | y    || invalid
    s1 = emptyAsNull(s1);
    s2 = emptyAsNull(s2);
    if (s1 == null) {
        // s2 can be either null or y
        return s2;
    }
    // x / null or x / x
    if (s2 == null || s1.equals(s2)) {
        return s1;
    }
    throw err.instance();
}

This method is defined in the io.nats.client.support.Validator class. It takes three parameters: s1 and s2 of type String, and err of type NatsJetStreamClientError. The purpose of this method is to validate whether s1 and s2 must match based on certain conditions.

Here is a step-by-step description of what the method does:

1. Assigns the value of s1 after converting empty string to null using the emptyAsNull helper method.
2. Assigns the value of s2 after converting empty string to null using the emptyAsNull helper method.
3. Checks if s1 is null:
   • If s1 is null, it means that it is either null or an empty string.
   • Then, it checks if s2 is null or equal to "y".
     • If s2 is either null or "y", it returns the value of s2.
     • This is considered a valid scenario.
4. If s1 is not null, it means that it has a non-empty value.
5. Checks if s2 is null or equal to s1:
   • If s2 is null or equal to s1, it returns the value of s1.
   • This is considered a valid scenario.
6. If none of the above conditions are met, it means that s1 and s2 have different non-null, non-empty values, which is considered an invalid scenario.
7. Throws an instance of NatsJetStreamClientError using the err.instance() method to indicate an invalid scenario.

The method essentially follows a set of conditions to determine whether s1 and s2 must match or not. It returns the appropriate value or throws an error based on these conditions.

The validateMustMatchIfBothSupplied method in the io.nats.client.support.Validator class is used to validate two string inputs, s1 and s2, and ensure that they match certain conditions.

The method starts by converting any empty strings to null using the emptyAsNull helper method.

The method then proceeds to check various combinations of s1 and s2 using a table:

• If both s1 and s2 are null, the method returns null, indicating a valid condition.
• If s1 is null and s2 is not null, the method returns s2, indicating a valid condition.
• If s1 is not null and s2 is null or s1 is equal to s2, the method returns s1, indicating a valid condition.
• If none of the above conditions are met, the method throws an exception using the provided NatsJetStreamClientError instance.

In summary, this method validates s1 and s2 based on the conditions described in the table and returns the appropriate value or throws an exception.

public static String required(String s, String label) {
    if (emptyAsNull(s) == null) {
        throw new IllegalArgumentException(label + " cannot be null or empty.");
    }
    return s;
}

The required method in the io.nats.client.support.Validator class is used to validate a string value and ensure that it is not null or empty. It takes two parameters:

1. s - the string value that needs to be validated.
2. label - the label or name of the string value, which is used in the error message if the validation fails.

Here is a step-by-step description of what the required method is doing:

1. Check if the s string value is empty or null by calling the emptyAsNull method, which is not provided in the given code snippet. Assuming that this method returns null if the string value is empty or null and returns the original string value otherwise.

2. If the result of emptyAsNull(s) is null, it means that the string value is either empty or null, which is considered invalid.

3. Throw an IllegalArgumentException with an error message indicating that the string value specified by the label parameter cannot be null or empty.

4. If the string value passes the validation, i.e., it is not empty or null, return the original string value.

In summary, the required method ensures that a string value is not null or empty and throws an IllegalArgumentException if it is.

The required method, defined in the io.nats.client.support.Validator class, is used to validate that a given string parameter is not null or empty.

The method takes two parameters: s, which is the string to be validated, and label, which is a label or description of the string parameter.

Inside the method, it first checks if the given string parameter is null or empty using the emptyAsNull helper method. If the string is null or empty, it throws an IllegalArgumentException with a message indicating that the string parameter cannot be null or empty, using the provided label.

If the string is not null or empty, the method simply returns the original string.

This method is useful for enforcing that a required string parameter is provided, and can be used to validate user input or ensure that necessary data is provided before continuing with further processing.

public static <T> T required(T o, String label) {
    if (o == null) {
        throw new IllegalArgumentException(label + " cannot be null or empty.");
    }
    return o;
}

This method is defined in the io.nats.client.support.Validator class and is used to validate if a given object o is null or not.

The method has the following signature:

public static <T> T required(T o, String label) {
    // Method body
}

• o: The object that needs to be validated.
• label: A string value representing a label or description for the object o.

This method returns the validated object o if it is not null.

The method body checks if the object o is null using the condition o == null. If the condition evaluates to true, it throws an IllegalArgumentException with an error message formatted as "{label} cannot be null or empty.", where {label} is the value passed as the label parameter.

If the object o is not null, it directly returns the object o.

String text = "Sample Text";
String validatedText = Validator.required(text, "Text");

// The value of 'validatedText' will be "Sample Text"

In the above example, the required() method is used to validate if the text object is null or not. Since the text object is not null, it is returned as the validated object.

The required method in the io.nats.client.support.Validator class is a static method that takes two parameters: an object of type T (o) and a String (label).

This method is used to check if the object o is null. If o is null, the method throws an IllegalArgumentException with a descriptive message indicating that the label (provided as a parameter) cannot be null or empty.

Otherwise, if o is not null, the method simply returns the object o.

This method is typically used to validate that a required parameter or argument in a method call is provided, and it serves as a convenient way to enforce a non-null value.

public static String _validate(String s, boolean required, String label, Check check) {
    if (emptyAsNull(s) == null) {
        if (required) {
            throw new IllegalArgumentException(label + " cannot be null or empty.");
        }
        return null;
    }
    return check.check();
}

The method _validate in the class io.nats.client.support.Validator performs the following steps:

1. The method takes four parameters:

   • s: A string to be validated.
   • required: A boolean value indicating whether the string is required.
   • label: A string label for the parameter being validated.
   • check: An instance of the Check functional interface which provides a check method to be executed.

2. If the string s is empty or null (determined by the emptyAsNull method), the following actions are taken:

   • If required is true, an IllegalArgumentException is thrown with a message indicating that the label cannot be null or empty.
   • If required is false, null is returned.

3. If the string s is not empty or null, the check.check() method is called. The purpose of this method is not specified in the given code snippet, but it is expected to perform some kind of validation or processing on the provided string. The return value of the check method is then returned from the _validate method.

Note: The implementation of the emptyAsNull method and the exact behavior of the check method are not available in the provided code snippet, so further analysis would be required to understand their functionality.

The _validate method is a static method defined in the Validator class in the io.nats.client.support package.

This method takes four parameters:

1. String s - the value to be validated
2. boolean required - specifies whether the value is required or not
3. String label - a label for the value being validated (used for error messages)
4. Check check - an instance of the Check interface, which is responsible for performing the actual validation logic

The purpose of this method is to validate a given value based on the specified requirements.

First, it checks if the value is empty or null by invoking the emptyAsNull method (which is not shown in the provided code). If the value is empty or null and it is marked as required, it throws an IllegalArgumentException with an appropriate error message.

If the value is not empty or null, it then calls the check.check() method, which is responsible for performing the actual validation logic. The return value of this method is then returned by the _validate method.

Overall, this method provides a reusable way to validate a value based on the specified requirements and perform custom validation logic using the Check interface.

public static String validateMaxLength(String s, int maxLength, boolean required, String label) {
    return _validate(s, required, label, () -> {
        int len = s.getBytes(StandardCharsets.UTF_8).length;
        if (len > maxLength) {
            throw new IllegalArgumentException(label + " cannot be longer than " + maxLength + " bytes but was " + len + " bytes");
        }
        return s;
    });
}

The validateMaxLength method in the io.nats.client.support.Validator class is used to validate a string against a maximum length. Here is a step-by-step description of what the method does:

1. The method takes four parameters:

   • s - the string to be validated
   • maxLength - the maximum length allowed for the string
   • required - a boolean value indicating if the string is required or not
   • label - a label to identify the string in case of an error message

2. The method calls the _validate method, passing the s, required, label, and a lambda expression as parameters. The lambda expression is used to define the validation logic.

3. Inside the lambda expression, the method calculates the length of the string in bytes using the UTF-8 character encoding. The getBytes method is used to convert the string to a byte array, and the length property of the byte array is then used to get the length in bytes.

4. If the length of the string is greater than the maxLength parameter, an IllegalArgumentException is thrown. The exception message includes the label, maxLength, and the actual length of the string in bytes.

5. If the string passes the length validation, it is returned as the result of the method.

In summary, the validateMaxLength method checks if a given string exceeds a maximum length in bytes. It throws an exception if the length is exceeded and returns the string if it is within the allowed length.

The validateMaxLength method, defined in the Validator class in the io.nats.client.support package, is used to validate if a given string s is not longer than a specified maxLength in bytes.

The method takes four parameters:

• s: The string to be validated.
• maxLength: The maximum allowed length of the string in bytes.
• required: A boolean value indicating whether the string is required or not.
• label: A label to identify the string being validated.

Internally, the method calculates the length of the string s in bytes using the UTF-8 character encoding. If the length exceeds the maxLength, the method throws an IllegalArgumentException with an error message indicating the violation.

If the string passes the validation, it is returned unchanged.

Overall, validateMaxLength provides a convenient way to validate the maximum length of a string in bytes while considering the UTF-8 encoding.

public static String validatePrintable(String s, String label, boolean required) {
    return _validate(s, required, label, () -> {
        if (notPrintable(s)) {
            throw new IllegalArgumentException(label + " must be in the printable ASCII range [" + s + "]");
        }
        return s;
    });
}

The validatePrintable method, defined in the io.nats.client.support.Validator class, is responsible for validating a given string s based on its printability in the ASCII range. It takes three parameters: the string to validate s, a label for the string label, and a boolean flag indicating whether the string is required or not required.

Here's a step-by-step breakdown of what the method is doing:

1. The method delegates the actual validation to the _validate method, passing in the string s, the boolean flag required, the string label label, and a lambda expression.

2. The lambda expression () -> { ... } defines an inline function that is executed within the _validate method.

3. Within the lambda expression, the method first checks if the string s is not printable by calling the notPrintable function. If the string is not printable, an IllegalArgumentException is thrown. The exception message includes the label and the actual string value.

4. If the string is printable, the method returns the original string s.

Overall, the validatePrintable method ensures that a given string is within the printable ASCII range and throws an exception if it is not.

The validatePrintable method in the Validator class is a public static method that takes three parameters:

1. s - a String that needs to be validated
2. label - a String representing the label of the value being validated
3. required - a boolean indicating if the value is required to be non-null and non-empty

The purpose of this method is to validate that the provided s parameter contains only printable ASCII characters. If the s parameter contains any characters that are not within the printable ASCII range, an IllegalArgumentException is thrown with an error message indicating the violation.

The underlying implementation of this method involves calling a private method _validate from within the validatePrintable method, passing in the necessary parameters. This private method handles the common validation logic for various types of validations and returns the validated s parameter if it passes all the validation checks.

public static String validatePrintableExceptWildDotGt(String s, String label, boolean required) {
    return _validate(s, required, label, () -> {
        if (notPrintableOrHasWildGtDot(s)) {
            throw new IllegalArgumentException(label + " must be in the printable ASCII range and cannot include `*`, `.` or `>` [" + s + "]");
        }
        return s;
    });
}

The validatePrintableExceptWildDotGt method is a static method defined in the Validator class located in the io.nats.client.support package. It takes three parameters: String s, String label, and boolean required. It returns a String.

Here is a step-by-step description of what this method does:

1. It calls the _validate method passing in the s parameter, required parameter, label parameter, and a lambda expression as arguments. This method is responsible for performing the actual validation and throwing an exception if the validation fails.

2. Inside the lambda expression, it checks whether the s string is not in the printable ASCII range or contains the characters *, ., or >. This check is done using the notPrintableOrHasWildGtDot method.

3. If the check in step 2 fails, it throws an IllegalArgumentException with a message that includes the label, the invalid string s, and a description of the invalid characters.

4. If the check in step 2 passes, it returns the original string s.

Overall, this method is used to validate a string s to ensure that it is in the printable ASCII range and does not contain the characters *, ., or >. If the validation fails, an exception is thrown.

The method validatePrintableExceptWildDotGt in the class Validator is used to validate a string s to ensure that it is in the printable ASCII range and does not include the characters *, ., or >.

If the string s is not printable or contains any of the prohibited characters, an IllegalArgumentException is thrown with a message indicating the invalid characters found in the string.

Otherwise, the method returns the validated string s.

public static String validatePrintableExceptWildDotGtSlashes(String s, String label, boolean required) {
    return _validate(s, required, label, () -> {
        if (notPrintableOrHasWildGtDotSlashes(s)) {
            throw new IllegalArgumentException(label + " must be in the printable ASCII range and cannot include `*`, `.`, `>`, `\\` or  `/` [" + s + "]");
        }
        return s;
    });
}

The validatePrintableExceptWildDotGtSlashes method is defined in the io.nats.client.support.Validator class. This method is used to validate a string and ensure that it only contains printable ASCII characters, except for the characters *, ., >, \, or /.

public static String validatePrintableExceptWildDotGtSlashes(String s, String label, boolean required)

• s : The string to be validated
• label : The label or name of the string being validated
• required : A boolean flag indicating whether the string is required or not

• The validated string s

The method call _validate(s, required, label, () -> {...}) is used to perform the validation. It uses a lambda expression to define the validation logic.

The validation logic checks if the string s is not printable or contains any of the following characters: *, ., >, \, or /. If the validation fails, an IllegalArgumentException is thrown with an error message that includes the label and the invalid string. Otherwise, the method returns the validated string s.

Example error message:

[label] must be in the printable ASCII range and cannot include `*`, `.`, `>`, `\` or  `/` [invalidString]

• IllegalArgumentException: Thrown if the validation fails

The validatePrintableExceptWildDotGtSlashes method is a static method defined in the Validator class within the io.nats.client.support package. This method takes three parameters: s, label, and required.

The purpose of this method is to validate the input string s and ensure that it contains only printable ASCII characters, excluding specific characters such as *, ., >, \, and /. If the input string s contains any of these forbidden characters or is not within the printable ASCII range, an IllegalArgumentException is thrown with a descriptive message including the label and the invalid input.

The method follows a functional programming style, making use of a lambda expression to perform the actual validation. The lambda expression checks if the input string s is not printable or contains any of the forbidden characters using the notPrintableOrHasWildGtDotSlashes method. If any of these conditions are true, the validation fails and an IllegalArgumentException is thrown. Otherwise, the validated string s is returned.

Overall, the validatePrintableExceptWildDotGtSlashes method ensures that the input string s meets the required criteria of being printable while excluding specific forbidden characters.

public static String validatePrintableExceptWildGt(String s, String label, boolean required) {
    return _validate(s, required, label, () -> {
        if (notPrintableOrHasWildGt(s)) {
            throw new IllegalArgumentException(label + " must be in the printable ASCII range and cannot include `*` or `>` [" + s + "]");
        }
        return s;
    });
}

The validatePrintableExceptWildGt method is defined in the io.nats.client.support.Validator class. It takes three parameters:

1. s - A string that needs to be validated.
2. label - A string label that provides context to the validation process.
3. required - A boolean flag that indicates whether the string is required or not.

The purpose of this method is to validate the input string s and ensure that it only contains printable characters from the ASCII range, except for the characters * and >. The validation process includes checking if the string is required and whether it meets the specified criteria.

The method calls a private method _validate to handle the validation process. Here is a step-by-step description of what happens in the method body:

1. The method delegates the validation process to the _validate method, passing the input string s, the required flag, the provided label, and a lambda expression.

2. The lambda expression represents the validation logic. It checks if the input string s is not printable or contains the characters * or >. If any of these conditions are true, it throws an IllegalArgumentException with a descriptive error message that includes the label and the input string s.

3. If the lambda expression's validation logic passes without any exceptions being thrown, the method returns the input string s.

Overall, the validatePrintableExceptWildGt method ensures that the input string s is valid, printable, and does not contain the characters * or >. If the validation fails, it throws an exception with a detailed error message.

The method validatePrintableExceptWildGt in the Validator class is used to validate a string by checking if it contains any characters that are not within the printable ASCII range, and also if it includes the characters * or >.

The method takes three parameters: s (the string to be validated), label (a label that describes the string), and required (a boolean value indicating if the string is required).

If the string s is not printable or contains * or >, an IllegalArgumentException is thrown with a message indicating that the string must be in the printable ASCII range and cannot include * or >, along with the invalid string.

If the validation passes, the method returns the validated string s.

The method uses an underlying private method _validate to handle the common logic of validating the string and throwing an exception if necessary.

public static String validateIsRestrictedTerm(String s, String label, boolean required) {
    return _validate(s, required, label, () -> {
        if (notRestrictedTerm(s)) {
            throw new IllegalArgumentException(label + " must only contain A-Z, a-z, 0-9, `-` or `_` [" + s + "]");
        }
        return s;
    });
}

This method is a static method defined in class io.nats.client.support.Validator. It takes three parameters:

1. String s: The input string that needs to be validated.
2. String label: A label or name for the input string. This is used in exception messages for readability.
3. boolean required: A flag indicating whether the input string is required (true) or optional (false).

The method returns a String value, which is the validated input string if it passes all the checks.

public static String validateIsRestrictedTerm(String s, String label, boolean required)

1. The method calls a private method _validate with the input string s, the required flag, the label, and a lambda expression as parameters. The lambda expression contains the actual validation logic.
2. Inside the lambda expression, the method checks if the input string s is not a restricted term. If it is not a restricted term, an IllegalArgumentException is thrown with a specific message indicating that the input string must only contain A-Z, a-z, 0-9, -, or _.
3. If the input string passes the check, it is returned as the result of the method.

Please note that the actual implementation of the _validate and notRestrictedTerm methods is not provided in the given code snippet.

The method validateIsRestrictedTerm in the class Validator is used to check if a given string contains restricted terms. It takes three parameters: s (the string to be validated), label (a descriptive label for the string), and required (a boolean indicating if the string is required or not).

The method calls a private helper method _validate passing the string, label, and required as arguments, along with a lambda expression that performs the actual validation.

Inside the lambda expression, the method checks if s is not a restricted term by calling the notRestrictedTerm function. If s is not a restricted term, an IllegalArgumentException is thrown with a message indicating that the string should only contain letters, numbers, hyphens, or underscores.

If the string passes the validation, it is returned as the result of the method.

public static String validateWildcardKvKey(String s, String label, boolean required) {
    return _validate(s, required, label, () -> {
        if (notWildcardKvKey(s)) {
            throw new IllegalArgumentException(label + " must only contain A-Z, a-z, 0-9, `*`, `-`, `_`, `/`, `=`, `>` or `.` and cannot start with `.` [" + s + "]");
        }
        return s;
    });
}

This method is defined in the io.nats.client.support.Validator class and is used to validate wildcard key-value pairs.

The method takes the following parameters:

• s (String): The key-value pair to be validated.
• label (String): The label or name of the key-value pair.
• required (boolean): Indicates whether the key-value pair is required or optional.

The method returns a String value.

The method performs the following steps:

1. It calls the _validate method passing the s, required, label, and a lambda expression as arguments.
2. Inside the lambda expression, it checks if the key-value pair does not match the required pattern by calling the notWildcardKvKey method.
3. If the key-value pair is invalid, it throws an IllegalArgumentException with an error message indicating the invalid characters in the key-value pair.
4. If the key-value pair is valid, it returns the key-value pair.

Note: The notWildcardKvKey method is not provided in the given code snippet, so the details of its implementation are unknown. This method is likely used to check if the given key-value pair matches a specific pattern.

The validateWildcardKvKey method in the Validator class is used to validate a given string s as a wildcard key-value key.

The method takes three parameters:

• s: The string to be validated
• label: A label used for error messages
• required: A flag indicating whether the string is required or not

The method calls a private method _validate passing in the string s, the required flag, the label, and a lambda expression. If the string s does not meet the validation criteria, an IllegalArgumentException is thrown with an appropriate error message indicating that the string must only contain certain characters and cannot start with a dot.

If the string s passes the validation, it is returned unchanged.

public static String validateNonWildcardKvKey(String s, String label, boolean required) {
    return _validate(s, required, label, () -> {
        if (notNonWildcardKvKey(s)) {
            throw new IllegalArgumentException(label + " must only contain A-Z, a-z, 0-9, `-`, `_`, `/`, `=` or `.` and cannot start with `.` [" + s + "]");
        }
        return s;
    });
}

The validateNonWildcardKvKey method within the io.nats.client.support.Validator class is responsible for validating a given key string based on specific criteria.

Here is a step-by-step description of what the method is doing:

1. The method accepts three parameters:

   • s - the key string to be validated
   • label - a label to describe the key (used in exception messages)
   • required - a flag indicating if the key is required or not

2. The method calls a private method _validate with the parameters s, required, label, and a lambda expression.

3. Within the lambda expression, the method checks if the key string s does not meet the criteria of a non-wildcard key by calling the notNonWildcardKvKey helper method. If the key string does not meet the criteria, an IllegalArgumentException is thrown with an informative error message.

4. The error message indicates that the key must only contain letters A-Z (uppercase and lowercase), digits 0-9, hyphen (-), underscore (_), forward slash (/), equal sign (=), or period (.). Additionally, the key cannot start with a period. The original key string that failed the validation is included in the error message.

5. If the key string passes all the validation checks, it is returned as the result of the method.

Note: The implementation of the notNonWildcardKvKey method is not provided in the given code snippet. Its purpose is to determine if the key string violates the criteria for a non-wildcard key.

The validateNonWildcardKvKey method is a static method in the Validator class that takes in three parameters: a String s, a String label, and a boolean required.

This method is used to validate a non-wildcard key (s) for a key-value pair. It ensures that the key only contains valid characters and does not violate any restrictions.

If the key is found to be invalid, an IllegalArgumentException is thrown, with a detailed error message indicating the specific validation failure. If the key is deemed valid, it is returned as the output of the method.

public static int validateMaxHistory(int max) {
    if (max < 1 || max > MAX_HISTORY_PER_KEY) {
        throw new IllegalArgumentException("Max History must be from 1 to " + MAX_HISTORY_PER_KEY + " inclusive.");
    }
    return max;
}

This method is defined in the class io.nats.client.support.Validator. It takes an integer parameter max and returns an integer value.

• max (type: int): The value to be validated.

1. Check if the value of max is less than 1 or greater than a constant value MAX_HISTORY_PER_KEY.
2. If the condition in step 1 is true, throw an IllegalArgumentException with a message stating that the max value must be between 1 and MAX_HISTORY_PER_KEY, inclusive.
3. If the condition in step 1 is false, return the max value.

• The validated max value.

The validateMaxHistory method in the Validator class of the io.nats.client.support package is used to validate a given maximum history value.

The method takes an integer parameter max, representing the maximum history value to be validated. It checks if the value is less than 1 or greater than a constant variable MAX_HISTORY_PER_KEY. If either of these conditions is true, it throws an IllegalArgumentException with an error message stating that the maximum history must be between 1 and MAX_HISTORY_PER_KEY, inclusive.

If the input value passes the validation, it simply returns the value itself.

This method is useful in ensuring that the maximum history value provided by the caller falls within the permissible range.

public static int validateNumberOfReplicas(int replicas) {
    if (replicas < 1 || replicas > 5) {
        throw new IllegalArgumentException("Replicas must be from 1 to 5 inclusive.");
    }
    return replicas;
}

The method validateNumberOfReplicas is defined in the class io.nats.client.support.Validator and is responsible for validating the number of replicas passed as an argument.

Here is a step-by-step description of what this method does based on its body:

1. The method takes an integer argument replicas.

2. It checks if the value of replicas is less than 1 or greater than 5 using the logical OR operator (||).

3. If the condition evaluates to true, it means that the value of replicas is either less than 1 or greater than 5, which is invalid. In this case, an IllegalArgumentException is thrown with the message "Replicas must be from 1 to 5 inclusive." This exception is used to indicate that an illegal argument has been passed to the method.

4. If the condition in step 2 evaluates to false, it means that the value of replicas is within the valid range of 1 to 5 inclusive.

5. In this case, the method simply returns the value of replicas.

Overall, the purpose of this method is to ensure that the number of replicas provided is within the valid range of 1 to 5. If an invalid value is detected, it throws an exception, otherwise, it returns the given replica count as is.

The method validateNumberOfReplicas, defined in the class io.nats.client.support.Validator, is used to validate the number of replicas in a system. It takes an integer argument replicas and checks if it is within the valid range of 1 to 5 (inclusive). If the replicas value is outside this range, an IllegalArgumentException is thrown with an appropriate error message. If the replicas value is valid, it is returned as the output of the method.

This method is useful to ensure that the number of replicas specified for a system is within a valid and supported range. If the replicas value is invalid, it can lead to unexpected behavior or errors in the system.

public static Duration validateDurationRequired(Duration d) {
    if (d == null || d.isZero() || d.isNegative()) {
        throw new IllegalArgumentException("Duration required and must be greater than 0.");
    }
    return d;
}

Method Definition: The validateDurationRequired method is defined in the io.nats.client.support.Validator class as a public static method.

Method Signature: public static Duration validateDurationRequired(Duration d)

Method Description: This method takes a Duration object as input and validates it to ensure that it is not null, not zero, and not negative.

Step-by-Step Description:

1. Check if the input Duration object, d, is null or if it is equal to zero or if it is negative.
2. If any of the above conditions are true, throw an IllegalArgumentException with the message "Duration required and must be greater than 0."
3. If none of the above conditions are true, return the input Duration object, d.

The validateDurationRequired method in the io.nats.client.support.Validator class checks if a provided Duration meets specific requirements. The method takes in a Duration object as a parameter.

If the provided Duration is null, zero, or negative, the method throws an IllegalArgumentException with the message "Duration required and must be greater than 0.". Otherwise, it returns the provided Duration.

This method is used to ensure that a valid and non-zero Duration value is provided, rejecting any invalid inputs.

public static Duration validateDurationNotRequiredGtOrEqZero(Duration d, Duration ifNull) {
    if (d == null) {
        return ifNull;
    }
    if (d.isNegative()) {
        throw new IllegalArgumentException("Duration must be greater than or equal to 0.");
    }
    return d;
}

The method validateDurationNotRequiredGtOrEqZero in the class io.nats.client.support.Validator performs the following steps:

1. Check if the input d is null.

   • If d is null, return the input ifNull duration.

2. Check if the input d is negative.

   • If d is negative, throw an IllegalArgumentException with the message "Duration must be greater than or equal to 0."

3. If both conditions are false, return the input d duration.

This method is used to validate a Duration object, ensuring that it is not null and greater than or equal to 0.

The method validateDurationNotRequiredGtOrEqZero checks if a given Duration is greater than or equal to zero. If the duration is null, it returns a specified default value (ifNull). If the duration is negative, it throws an IllegalArgumentException with a descriptive error message. If the duration is valid (greater than or equal to zero), it returns the duration itself.

public static Duration validateDurationNotRequiredGtOrEqZero(long millis) {
    if (millis < 0) {
        throw new IllegalArgumentException("Duration must be greater than or equal to 0.");
    }
    return Duration.ofMillis(millis);
}

This method is defined in the class io.nats.client.support.Validator and is used to validate a duration value to ensure that it is greater than or equal to zero.

public static Duration validateDurationNotRequiredGtOrEqZero(long millis)

if (millis < 0) {
    throw new IllegalArgumentException("Duration must be greater than or equal to 0.");
}
return Duration.ofMillis(millis);

The method validateDurationNotRequiredGtOrEqZero takes a long value representing duration in milliseconds as input.

1. Check if the input millis is less than zero.
2. If step 1 is true, throw an IllegalArgumentException with the message "Duration must be greater than or equal to 0."
3. If step 1 is false, create a Duration object using the value of millis as the duration in milliseconds.
4. Return the created Duration object.

Note: The purpose of this method is to ensure that the duration value provided is valid and meets the requirement of being greater than or equal to zero.

The validateDurationNotRequiredGtOrEqZero method is a static method defined in the Validator class in the io.nats.client.support package.

This method takes a long parameter millis representing a duration in milliseconds. It validates that the duration is not negative (i.e., greater than or equal to zero). If the duration is negative, it throws an IllegalArgumentException with the message "Duration must be greater than or equal to 0."

If the duration is valid (greater than or equal to zero), it returns a Duration object representing the specified number of milliseconds.

public static String validateNotNull(String s, String fieldName) {
    if (s == null) {
        throw new IllegalArgumentException(fieldName + " cannot be null");
    }
    return s;
}

The validateNotNull method is a static method defined in the io.nats.client.support.Validator class. This method takes two parameters: a string s and a string fieldName. The purpose of this method is to validate that the provided string (s) is not null.

The method implementation starts with an if statement that checks if the s parameter is null. If it is null, an IllegalArgumentException is thrown with a message that includes the fieldName parameter. This exception indicates that the provided field name cannot be null.

If the s parameter is not null, the method simply returns the s string.

In summary, the validateNotNull method ensures that the provided string is not null, and if it is null, it throws an exception. Otherwise, it returns the string as is.

The validateNotNull method in the io.nats.client.support.Validator class is a static method that validates whether a given string s is not null.

If the s string is null, it throws an IllegalArgumentException with a message stating that the fieldName (provided as a parameter) cannot be null.

The method returns the same string s if it is not null.

public static Object validateNotNull(Object o, String fieldName) {
    if (o == null) {
        throw new IllegalArgumentException(fieldName + " cannot be null");
    }
    return o;
}

This method is defined in the io.nats.client.support.Validator class. It takes in two parameters, an Object o and a String fieldName. The purpose of this method is to validate that the given object is not null.

The method starts by checking if the parameter o is null using the == operator. If the object is indeed null, an IllegalArgumentException is thrown, with the error message constructed by concatenating the fieldName parameter with the string " cannot be null".

If the object is not null, the method simply returns the object.

It is important to note that this method does not modify the object in any way; it is purely used for validation purposes.

The validateNotNull method in the io.nats.client.support.Validator class is used to validate that an object is not null.

The method takes two parameters: o, which is the object to be validated, and fieldName, which is a string representing the name of the field being checked.

If the o parameter is null, the method throws an IllegalArgumentException with a message that includes the fieldName. Otherwise, if the o parameter is not null, the method simply returns the object.

public static int validateGtZero(int i, String label) {
    if (i < 1) {
        throw new IllegalArgumentException(label + " must be greater than zero");
    }
    return i;
}

The validateGtZero method, defined in the io.nats.client.support.Validator class, is responsible for validating whether a given integer value is greater than zero.

public static int validateGtZero(int i, String label)

• int i: the integer value to be validated
• String label: the label associated with the integer value, used for error messaging purposes

• Returns the validated integer value i if it is greater than zero

1. Check if the value of i is less than 1.
2. If the above condition is true, throw an IllegalArgumentException with the error message format: label + " must be greater than zero".
3. If the value of i is greater than zero, return i.

The method validateGtZero defined in class io.nats.client.support.Validator is a static method that takes an integer i and a string label as parameters.

The purpose of this method is to validate that the integer i is greater than zero. If the condition i < 1 is not met, meaning that i is less than or equal to zero, an IllegalArgumentException is thrown with a message stating that the given label should be greater than zero.

If the condition is met and i is greater than zero, the method returns the same integer i.

In summary, the validateGtZero method ensures that the provided integer value is higher than zero, throwing an exception if not, and returning the integer value otherwise.

public static long validateGtZeroOrMinus1(long l, String label) {
    if (zeroOrLtMinus1(l)) {
        throw new IllegalArgumentException(label + " must be greater than zero or -1 for unlimited");
    }
    return l;
}

This method, validateGtZeroOrMinus1, is defined in the io.nats.client.support.Validator class. It takes two parameters: l, which is a long value, and label, which is a String.

The purpose of this method is to validate the l value, ensuring that it is either greater than zero or equal to -1. If the l value does not meet this condition, an IllegalArgumentException is thrown with a message indicating that the label must be greater than zero or equal to -1 for unlimited.

public static long validateGtZeroOrMinus1(long l, String label)

• l - the long value that needs to be validated.
• label - the String label used for generating an error message if the validation fails.

• long - the validated value of l.

if (zeroOrLtMinus1(l)) {
    throw new IllegalArgumentException(label + " must be greater than zero or -1 for unlimited");
}
return l;

1. The method checks if the l value satisfies the condition specified by the zeroOrLtMinus1 method (implementation details not provided). This condition is meant to determine if l is either zero or less than -1.
2. If the condition is satisfied, an IllegalArgumentException is thrown with an error message stating that the label must be greater than zero or equal to -1 for unlimited.
3. If the condition is not satisfied, the method returns the original l value.
4. The method execution completes.

The validateGtZeroOrMinus1 method in the Validator class within the io.nats.client.support package is used to validate if a given long value is greater than zero or equal to -1.

If the value passed as the first argument is equal to or less than zero, an IllegalArgumentException is thrown with a message indicating that the value specified by the label parameter must be greater than zero or -1 for unlimited.

If the value is greater than zero or equal to -1, it is returned as the result of the method.

public static long validateGtEqMinus1(long l, String label) {
    if (l < -1) {
        throw new IllegalArgumentException(label + " must be greater than zero or -1 for unlimited");
    }
    return l;
}

The validateGtEqMinus1 method is defined in the class io.nats.client.support.Validator. It takes in two parameters: l of type long and label of type String.

The method checks if the value of l is less than -1 using the condition l < -1.

If the value of l is less than -1, an IllegalArgumentException is thrown with the message label + " must be greater than zero or -1 for unlimited". This exception indicates that the label value must be greater than zero or equal to -1 in order to proceed.

If the value of l is greater than or equal to -1, the method simply returns the value of l.

The validateGtEqMinus1 method in the Validator class, defined in the io.nats.client.support package, is used to validate if a given long value is greater than or equal to -1.

The method takes two parameters: l (the long value to be validated) and label (a string indicating the label or name of the value being validated).

Inside the method, it checks if the long value l is less than -1. If it is, an IllegalArgumentException is thrown with a message indicating that the value must be greater than zero or -1 for unlimited.

If the value passes the validation, it is returned without any modifications.

This method ensures that the long value provided is valid and meets the required criteria, helping to maintain data integrity and prevent incorrect usage of the value in the code.

public static long validateNotNegative(long l, String label) {
    if (l < 0) {
        throw new IllegalArgumentException(label + " cannot be negative");
    }
    return l;
}

The validateNotNegative method is defined in the io.nats.client.support.Validator class. It takes two parameters: a long value l and a String label.

The purpose of this method is to validate that the provided long value is not negative. It ensures that the value is greater than or equal to zero.

Here is a step-by-step description of what the method does:

1. Check if the value of l is less than zero:

   • If l is indeed less than zero, it means that the value is negative.
   • In such a case, an IllegalArgumentException is thrown with a message that includes the provided label.
   • The message states that the value cannot be negative.
   • This exception serves as an indicator that the provided value is invalid.

2. If the value of l is not negative, it means it is valid.

   • The method continues execution and returns the provided value l.

By utilizing this method, you can verify that a given long value is not negative by calling Validator.validateNotNegative and providing the value to validate along with a label for identification.

The validateNotNegative method in the Validator class, defined in the io.nats.client.support package, is responsible for checking if a given long value is not negative.

The method takes two parameters: l, which is the long value to be validated, and label, which is a string label used in the exception message if the value is negative.

If the value of l is less than 0, the method throws an IllegalArgumentException, with the message "label cannot be negative", where label is the provided string label concatenated with the message.

If the value is non-negative, the method simply returns the value.

This method can be used to enforce the constraint that a certain long value should always be non-negative.

public static long validateGtEqZero(long l, String label) {
    if (l < 0) {
        throw new IllegalArgumentException(label + " must be greater than or equal to zero");
    }
    return l;
}

The method validateGtEqZero in the io.nats.client.support.Validator class is responsible for validating if a given value is greater than or equal to zero. Here is a step-by-step description of how the method works:

1. Accept two parameters: l, which is the value to be validated, and label, which is a description of the value being checked.
2. Check if the value l is less than zero using the condition if (l < 0).
3. If the value is less than zero, it indicates that the value is invalid.
4. Throw an IllegalArgumentException with a custom error message. The error message consists of the provided label followed by the string "must be greater than or equal to zero".
5. If the value is greater than or equal to zero, it indicates that the value is valid.
6. Return the value l as it has been successfully validated.

This method is useful when you want to ensure that a given value is not negative but is instead greater than or equal to zero. By throwing an exception when the value is invalid, it provides a clear indication of the validation failure and allows for proper error handling in the calling code.

The validateGtEqZero method in the Validator class of the io.nats.client.support package checks if a given long value is greater than or equal to zero.

If the value is less than zero, it throws an IllegalArgumentException with a specific message indicating that the value must be greater than or equal to zero.

Regardless of the comparison result, the method returns the original value.

// Helpers // ---------------------------------------------------------------------------------------------------- public static boolean nullOrEmpty(String s)

// ----------------------------------------------------------------------------------------------------
// Helpers
// ----------------------------------------------------------------------------------------------------
public static boolean nullOrEmpty(String s) {
    return s == null || s.trim().length() == 0;
}

The nullOrEmpty method in the io.nats.client.support.Validator class is a static helper method used to check if a given string is either null or empty. It follows the following steps:

1. Check if the input string s is null.
2. If s is null, return true to indicate that the string is null or empty.
3. If s is not null, trim the string using the trim() method.
4. Use the length() method to get the length of the trimmed string.
5. Check if the length of the trimmed string is 0.
6. If the length is 0, return true to indicate that the string is empty.
7. If the length is greater than 0, return false to indicate that the string is not empty.

Here is the method in code:

public static boolean nullOrEmpty(String s) {
    return s == null || s.trim().length() == 0;
}

This method provides a convenient way to check if a string is null or empty before performing any further processing or validation.

The nullOrEmpty method, defined in the io.nats.client.support.Validator class, is a helper method that checks whether a given string is null or empty.

The method takes a string s as input and returns a boolean value indicating whether the string is null or its trimmed length is 0.

This method is useful for validating string inputs in the context of the Nats client.

public static boolean notPrintable(String s) {
    for (int x = 0; x < s.length(); x++) {
        char c = s.charAt(x);
        if (c < 33 || c > 126) {
            return true;
        }
    }
    return false;
}

The method notPrintable is defined in the class io.nats.client.support.Validator and is used to determine if a given string contains any non-printable characters.

public static boolean notPrintable(String s)

• s : A string to be checked for non-printable characters.

• true if the string contains any non-printable characters.
• false if the string does not contain any non-printable characters.

1. Start the loop from x = 0 and continue as long as x is less than the length of the string s.
2. Get the character at index x from the string s and assign it to the variable c.
3. Check if the ASCII value of c is less than 33 or greater than 126.
   • If the condition is true, it means that c is a non-printable character.
   • In this case, return true to indicate that the string contains non-printable characters.
4. If the loop completes without finding any non-printable characters, return false to indicate that the string does not contain any non-printable characters.

The notPrintable method in the Validator class is a static method that takes a string as input and checks whether the string contains any non-printable characters. Non-printable characters are defined as characters with ASCII codes below 33 or above 126.

The method uses a loop to iterate through each character in the input string. If a character is found that falls outside the range of printable ASCII characters, the method returns true, indicating that the string contains non-printable characters. If no non-printable characters are found, the method returns false.

This method can be used to validate input strings and ensure that they only contain printable characters, which are typically characters that can be displayed or printed by most systems and devices.

public static boolean notPrintableOrHasChars(String s, char[] charsToNotHave) {
    for (int x = 0; x < s.length(); x++) {
        char c = s.charAt(x);
        if (c < 33 || c > 126) {
            return true;
        }
        for (char cx : charsToNotHave) {
            if (c == cx) {
                return true;
            }
        }
    }
    return false;
}

The notPrintableOrHasChars method is a static method defined in the io.nats.client.support.Validator class. This method takes two parameters:

• s : A string which needs to be checked for printable characters and the presence of specific characters.
• charsToNotHave : An array of characters that should not be present in the string s.

The purpose of this method is to determine if the given string s contains any non-printable characters or any of the characters specified in charsToNotHave. The method returns a boolean value indicating if any of these conditions are met.

The method accomplishes this by iterating over each character in the string s using a for loop. Inside the loop, each character is checked against two conditions:

1. If the character is less than 33 (c < 33) or greater than 126 (c > 126), it is considered a non-printable character. In this case, the method immediately returns true indicating that the string contains non-printable characters.

2. The character is then compared with each character in the charsToNotHave array using another for-each loop. If a match is found (c == cx), the method returns true indicating that the specific character is present in the string.

If neither of the above conditions is met within the loop, the method continues to the next character until all characters in the string have been checked. If the method reaches this point without returning true, it means that no non-printable or unwanted characters were found in the string, and it returns false.

The notPrintableOrHasChars method, defined in the io.nats.client.support.Validator class, checks if a given string s contains any characters that are not printable or are present in the charsToNotHave array.

Here's a breakdown of the method's behavior:

1. The method takes two parameters: s (the string to be checked) and charsToNotHave (an array of characters that should not be present in the string).

2. It iterates over each character in the input string s using a for loop.

3. For each character, it checks if it is not a printable character (ASCII value less than 33 or greater than 126). If so, it returns true.

4. It then iterates over each character cx in the charsToNotHave array and checks if the current character c is equal to any of these characters. If a match is found, it returns true.

5. If none of the non-printable characters or prohibited characters are found in the string, it returns false.

In summary, this method is used to validate whether a given string contains characters that are not printable or are listed in the charsToNotHave array.

public static boolean notRestrictedTerm(String s)

// restricted-term  = (A-Z, a-z, 0-9, dash 45, underscore 95)+
public static boolean notRestrictedTerm(String s) {
    for (int x = 0; x < s.length(); x++) {
        char c = s.charAt(x);
        if (c < '0') {
            // before 0
            if (c == '-') {
                // only dash is accepted
                continue;
            }
            // "not"
            return true;
        }
        if (c < ':') {
            // means it's 0 - 9
            continue;
        }
        if (c < 'A') {
            // between 9 and A is "not restricted"
            return true;
        }
        if (c < '[') {
            // means it's A - Z
            continue;
        }
        if (c < 'a') {
            // before a
            if (c == '_') {
                // only underscore is accepted
                continue;
            }
            // "not"
            return true;
        }
        if (c > 'z') {
            // 122 is z, characters after of them are "not restricted"
            return true;
        }
    }
    return false;
}

This method is used to check whether a given string contains any characters that are not allowed in a restricted term.

• s - A string which needs to be checked.

• boolean - Returns true if the string contains any characters that are not allowed in a restricted term, otherwise returns false.

1. Iterate over each character in the given string.
2. Check the value of the character against certain ASCII values to determine if it is a restricted character.
3. If the character is before '0' (ASCII value < 48), check if it is '-'. If it is, continue to the next character.
4. If the character is between '0' and ':' (ASCII values 48-57), it is a digit and is allowed in a restricted term. Continue to the next character.
5. If the character is between '9' and 'A' (ASCII values 58-65), it is not a restricted character. Return true.
6. If the character is between 'A' and '[' (ASCII values 65-91), it is a capital letter and is allowed in a restricted term. Continue to the next character.
7. If the character is between '[' and 'a' (ASCII values 91-97), it is not a restricted character. Return true.
8. If the character is between 'a' and 'z' (ASCII values 97-123), it is a lowercase letter and is allowed in a restricted term. Continue to the next character.
9. If the character has an ASCII value greater than 'z' (ASCII value > 122), it is not a restricted character. Return true.
10. If none of the above conditions are met for any character in the string, return false as it is a restricted term.

String term = "my_Term";
boolean isRestricted = notRestrictedTerm(term);
System.out.println(isRestricted); // Output: false

In the above example, the string "my_Term" is checked using the notRestrictedTerm method. Since all characters in the string are allowed in a restricted term, the method returns false.

The notRestrictedTerm method in the Validator class checks if a given string contains any characters that are not allowed in a restricted term.

The method iterates through each character of the string and checks its value against specific ASCII ranges.

• If the character is before the numerical range (less than '0'), it returns true, indicating that the string is not a restricted term.
• If the character is within the numerical range ('0' to '9'), it continues to the next character.
• If the character is between the numerical range and the uppercase alphabetical range, it returns true.
• If the character is within the uppercase alphabetical range ('A' to 'Z'), it continues to the next character.
• If the character is before the lowercase alphabetical range, it returns true.
• If the character is within the lowercase alphabetical range ('a' to 'z'), it continues to the next character.
• If the character is after the lowercase alphabetical range (greater than 'z'), it returns true.

If none of these conditions are met after iterating through all characters, the method returns false, indicating that the given string is a valid restricted term.

// kv-key-name = limited-term (dot limited-term)* public static boolean notNonWildcardKvKey(String s)

// limited-term = (A-Z, a-z, 0-9, dash 45, dot 46, fwd-slash 47, equals 61, underscore 95)+
// kv-key-name = limited-term (dot limited-term)*
public static boolean notNonWildcardKvKey(String s) {
    if (s.charAt(0) == '.') {
        // can't start with dot
        return true;
    }
    for (int x = 0; x < s.length(); x++) {
        char c = s.charAt(x);
        if (c < '0') {
            // before 0
            if (c == '-' || c == '.' || c == '/') {
                // only dash dot and fwd slash are accepted
                continue;
            }
            // "not"
            return true;
        }
        if (c < ':') {
            // means it's 0 - 9
            continue;
        }
        if (c < 'A') {
            if (c == '=') {
                // equals is accepted
                continue;
            }
            // between 9 and A is "not limited"
            return true;
        }
        if (c < '[') {
            // means it's A - Z
            continue;
        }
        if (c < 'a') {
            // before a
            if (c == '_') {
                // only underscore is accepted
                continue;
            }
            // "not"
            return true;
        }
        if (c > 'z') {
            // 122 is z, characters after of them are "not limited"
            return true;
        }
    }
    return false;
}

The notNonWildcardKvKey method in the io.nats.client.support.Validator class is used to validate a string s to determine if it is a valid key for a key-value pair in a limited-term format. Here is a step-by-step description of what the method is doing based on its body:

1. The method starts by checking if the first character of the string is a dot (.). If it is, the method returns true indicating that the key cannot start with a dot.

2. The method then enters a for loop to iterate over each character in the string.

3. Within the loop, the method checks the value of the current character c.

4. If c is less than the character '0', it means that c comes before the numbers 0-9. In this case, the method checks if c is equal to dash (-), dot (.), or forward slash (/) and if it is, it continues to the next character. If c is not one of these characters, the method returns true, indicating that the key contains a character that is not allowed before the numbers 0-9.

5. If c is between the characters '0' and '9', the method continues to the next character because it is a valid digit in the key.

6. If c is less than the character 'A', it means that c comes between the numbers 9 and the uppercase letters A-Z. In this case, the method checks if c is equal to equal sign (=) and if it is, it continues to the next character. If c is not an equal sign, the method returns true, indicating that the key contains a character that is not allowed between the numbers 9 and the uppercase letters A-Z.

7. If c is between the characters 'A' and 'Z', the method continues to the next character because it is a valid uppercase letter in the key.

8. If c is less than the character 'a', it means that c comes between the uppercase letters A-Z and the lowercase letters a-z. In this case, the method checks if c is equal to underscore (_) and if it is, it continues to the next character. If c is not an underscore, the method returns true, indicating that the key contains a character that is not allowed between the uppercase letters A-Z and the lowercase letters a-z.

9. If c is greater than the character 'z', it means that c comes after the lowercase letters a-z. In this case, the method returns true, indicating that the key contains a character that is not allowed after the lowercase letters a-z.

10. After iterating over all the characters in the string and not encountering any invalid characters, the method returns false, indicating that the key is valid.

This method can be used to validate whether a string is a valid key for a key-value pair in a limited-term format.

The notNonWildcardKvKey method is a static method defined in the Validator class of the io.nats.client.support package. It takes a string s as an input and returns a boolean value.

This method verifies if the input string s is a valid key for a key-value store based on specific criteria. The criteria for a valid key are that it must start with a character other than a dot (.), and can only contain alphanumeric characters (A-Z, a-z, 0-9), dash (-), dot (.), forward slash (/), equals (=), and underscore (_).

The method checks each character of the input string against these criteria using a series of if statements. If any character does not meet the criteria, the method returns true, indicating that the key is not valid. If all characters pass the criteria, the method returns false, indicating that the key is valid.

public static boolean notWildcardKvKey(String s)

// (A-Z, a-z, 0-9, star 42, dash 45, dot 46, fwd-slash 47, equals 61, gt 62, underscore 95)+
public static boolean notWildcardKvKey(String s) {
    if (s.charAt(0) == '.') {
        // can't start with dot
        return true;
    }
    for (int x = 0; x < s.length(); x++) {
        char c = s.charAt(x);
        if (c < '0') {
            // before 0
            if (c == '*' || c == '-' || c == '.' || c == '/') {
                // only star dash dot and fwd slash are accepted
                continue;
            }
            // "not"
            return true;
        }
        if (c < ':') {
            // means it's 0 - 9
            continue;
        }
        if (c < 'A') {
            if (c == '=' || c == '>') {
                // equals, gt is accepted
                continue;
            }
            // between 9 and A is "not limited"
            return true;
        }
        if (c < '[') {
            // means it's A - Z
            continue;
        }
        if (c < 'a') {
            // before a
            if (c == '_') {
                // only underscore is accepted
                continue;
            }
            // "not"
            return true;
        }
        if (c > 'z') {
            // 122 is z, characters after of them are "not limited"
            return true;
        }
    }
    return false;
}

This method, notWildcardKvKey, is defined in class io.nats.client.support.Validator. It takes a string s as input and checks if the string represents a valid key for a key-value pair.

1. Check if the first character of the input string s is a period (.).

   • If it is, return true as keys cannot start with a dot.

2. Iterate through each character c in the input string s.

   • For each character:
     • If it is less than the character '0':
       • Check if it is one of the allowed characters: '*', '-', '.', '/'.
         • If it is, continue to the next character.
         • If it is not, return true as only the allowed characters are accepted before '0'.
     • If it is less than the character ':' and greater than or equal to character '0', continue to the next character as it is a number (0-9).
     • If it is less than character 'A' and greater than character '9':
       • Check if it is one of the allowed characters: '=', '>'.
         • If it is, continue to the next character.
         • If it is not, return true as only the allowed characters are accepted between '9' and 'A'.
     • If it is less than character '[' and greater than or equal to character 'A', continue to the next character as it is an uppercase letter (A-Z).
     • If it is less than character 'a' and greater than character 'A':
       • Check if it is the allowed character '_'.
         • If it is, continue to the next character.
         • If it is not, return true as only the allowed character '_' is accepted before lowercase letters.
     • If it is greater than character 'z' (122 is the ASCII value of 'z'), return true as characters after 'z' are not limited.

3. If none of the above conditions are met, return false as the input string s represents a valid key for a key-value pair.

Note: The method follows a pattern-based validation where the characters in the input string are checked against specific ranges and allowed characters. Any character found outside the allowed ranges or characters will result in the method returning true, indicating that the input string is not a valid key.

The notWildcardKvKey method, defined in the Validator class of the io.nats.client.support package, is used to validate a key string for a key-value pair.

The method checks if the given string contains characters that follow the specified pattern, which includes uppercase letters (A-Z), lowercase letters (a-z), numbers (0-9), special characters like star (*), dash (-), dot (.), forward slash (/), equals (=), and greater than (>). The string can also contain an underscore (_) character.

The method ensures that the string does not start with a dot (.), as that is not allowed. It also performs checks for specific characters based on their ASCII values, rejecting any characters that do not meet the allowed criteria.

If the string meets the criteria, the method returns false, indicating that it is a valid key. If the string does not meet the criteria or violates the specified pattern, the method returns true, indicating that it is not a valid key.

public static String validateSemVer(String s, String label, boolean required) {
    return _validate(s, required, label, () -> {
        if (!isSemVer(s)) {
            throw new IllegalArgumentException(label + " must be a valid SemVer");
        }
        return s;
    });
}

The validateSemVer method, defined in the io.nats.client.support.Validator class, is used to validate a string representing a Semantic Version (SemVer) number. Here is a step-by-step description of what the method does:

1. The method takes three parameters: s (the string to be validated), label (a label used for error messages), and required (a boolean value indicating whether the string is required or not).

2. The method calls a private static method _validate and passes the s, required, label, and a lambda expression as arguments. The lambda expression is used to define the behavior in case of successful validation.

3. The _validate method performs the actual validation by checking if the string s is a valid SemVer number. If it is not, an IllegalArgumentException is thrown with an error message containing the label and the requirement that the value must be a valid SemVer number.

4. If the validation passes and the string is a valid SemVer number, the lambda expression defined in the _validate method is executed. This lambda expression returns the validated string s.

5. Finally, the validateSemVer method returns the validated string s as the result of the method call.

In summary, the validateSemVer method validates a string representation of a Semantic Version number by calling the _validate method, which performs the actual validation and throws an exception if the string is not a valid SemVer number. If the validation passes, the method returns the validated string.

The validateSemVer method in the Validator class is used to validate a given string s as a Semantic Version (SemVer) according to the SemVer specification.

The method takes three parameters:

• s - the string to be validated as a SemVer.
• label - a label or identifier for the string being validated.
• required - a boolean flag indicating whether the validated string is required or not.

The method internally calls a private _validate method, passing the required parameters along with a lambda expression that performs the actual validation. If the provided string s is not a valid SemVer, an IllegalArgumentException is thrown, with a specific error message indicating that the provided label must be a valid SemVer.

If the provided string s is valid according to the SemVer specification, it is returned as the result of the method.

public static <T> boolean listsAreEqual(List<T> l1, List<T> l2, boolean nullSecondEqualsEmptyFirst) {
    if (l1 == null) {
        return l2 == null;
    }
    if (l2 == null) {
        return nullSecondEqualsEmptyFirst && l1.size() == 0;
    }
    return l1.equals(l2);
}

The listsAreEqual method, defined in the io.nats.client.support.Validator class, compares two lists - l1 and l2 - to determine if they are equal. Here is a step-by-step description of what the method is doing:

1. Check if l1 is null:

• If l1 is null, proceed to step 2.
• If l1 is not null, proceed to step 3.

2. Check if l2 is also null:

• If l2 is null, return true, indicating that both lists are null and therefore equal.
• If l2 is not null, return false, indicating that l1 is null but l2 is not, so they are not equal.

3. Check if l2 is null:

• If l2 is null and nullSecondEqualsEmptyFirst is true, check if l1 is empty (i.e., it has a size of 0).
  • If l1 is empty, return true, indicating that both lists are empty and therefore equal.
  • If l1 is not empty, return false, indicating that l1 is not empty but l2 is, so they are not equal.
• If l2 is not null, proceed to step 4.

4. Use the equals() method to compare the contents of l1 and l2:

• If the contents of l1 and l2 are equal, return true.
• If the contents of l1 and l2 are not equal, return false.

Note: The equals() method used in step 4 will use the implementation of equals() provided by the elements in the lists l1 and l2.

The method listsAreEqual is a static method defined in the Validator class in the io.nats.client.support package.

This method takes two generic lists (l1 and l2) as inputs and a boolean flag (nullSecondEqualsEmptyFirst). It compares the equality of the two lists based on the following logic:

1. If the first list (l1) is null, the method checks if the second list (l2) is also null. If yes, it returns true, indicating that both lists are equal. If the second list is not null, it returns false, indicating that the lists are not equal.

2. If the first list (l1) is not null but the second list (l2) is null, the method checks if the nullSecondEqualsEmptyFirst flag is set to true and if the size of the first list is 0. If both conditions are met, it returns true, indicating that the lists are equal. Otherwise, it returns false.

3. If both lists are not null, the method uses the equals method of the first list (l1) to compare it with the second list (l2). If the lists are equal, it returns true. Otherwise, it returns false.

In summary, this method checks the equality of two lists, taking into account potential null lists and the option to treat a null second list as equal to an empty first list.

public static boolean mapsAreEqual(Map<String, String> m1, Map<String, String> m2, boolean nullSecondEqualsEmptyFirst) {
    if (m1 == null) {
        return m2 == null;
    }
    if (m2 == null) {
        return nullSecondEqualsEmptyFirst && m1.size() == 0;
    }
    if (m1.size() != m2.size()) {
        return false;
    }
    for (Map.Entry<String, String> entry : m1.entrySet()) {
        if (!entry.getValue().equals(m2.get(entry.getKey()))) {
            return false;
        }
    }
    return true;
}

The mapsAreEqual method is defined in the io.nats.client.support.Validator class. It takes in two Map<String, String> objects (m1 and m2) and a boolean flag (nullSecondEqualsEmptyFirst).

The purpose of this method is to compare two maps for equality. It returns true if the maps are equal and false otherwise.

Here is a step-by-step breakdown of what the method is doing:

1. If m1 is null, it checks if m2 is also null. If true, it means both maps are null and returns true. If m2 is not null, it returns false because they are not equal.

2. If m1 is not null, it checks if m2 is null. If true, it checks the value of the nullSecondEqualsEmptyFirst flag. If the flag is true and the size of m1 is 0, it means the second map is considered as an empty map, and it returns true. Otherwise, it returns false.

3. If both m1 and m2 are not null, it checks if the sizes of the two maps are equal. If they are not equal, it returns false.

4. If the sizes of both maps are equal, it iterates through each entry in m1.

5. For each entry, it retrieves the corresponding value from m2 using the key. If the value is not equal to the value in m1, it means the maps are not equal, and it returns false.

6. If all entries in m1 have been checked and they are equal to their corresponding values in m2, the method returns true indicating that the maps are equal.

The mapsAreEqual method, defined in the io.nats.client.support.Validator class, is used to compare two maps (m1 and m2) and determine if they are equal.

The method takes three parameters:

• m1: The first map to compare.
• m2: The second map to compare.
• nullSecondEqualsEmptyFirst: A boolean flag indicating whether a null second map should be considered equal to an empty first map.

The method first checks if m1 is null. If it is, the method returns true if m2 is also null, and false otherwise.

Next, it checks if m2 is null. If it is and nullSecondEqualsEmptyFirst is true, the method returns true if m1 is also empty (i.e., has a size of 0), and false otherwise.

If both maps are not null, the method checks if their sizes are equal. If they are not, the method returns false.

Finally, the method iterates over the entries of m1 using a for-each loop. For each entry, it compares the value in m1 to the corresponding value in m2 based on the key. If any pair of values are not equal, the method returns false. If all pairs are equal, the method returns true.

In summary, the mapsAreEqual method compares two maps, accounting for null maps and specifying whether a null second map should be considered equal to an empty first map. It returns true if the maps are equal and false otherwise.

SSLUtils

The SSLUtils class is a public class that provides utilities for working with SSL (Secure Sockets Layer) in software engineering. It includes methods and functionalities for managing SSL certificates, configuring SSL connections, and handling SSL exceptions. This class is designed to facilitate secure communication over network sockets using SSL protocols.

public static SSLContext createOpenTLSContext() {
    SSLContext context = null;
    try {
        context = SSLContext.getInstance(Options.DEFAULT_SSL_PROTOCOL);
        context.init(null, trustAllCerts, SRAND);
    } catch (Exception e) {
        context = null;
    }
    return context;
}

The createOpenTLSContext method in the SSLUtils class is used to create an SSLContext object for establishing a secure TLS connection.

Here is a step-by-step description of what the method does:

1. It declares a variable context of type SSLContext and initializes it to null.
2. It tries to create an SSLContext object using the getInstance method from the SSLContext class, passing in the value of Options.DEFAULT_SSL_PROTOCOL.
   • Options.DEFAULT_SSL_PROTOCOL typically specifies the default SSL/TLS protocol version to be used, such as "TLSv1.2".
3. It initializes the SSLContext object context by calling its init method, passing in the following parameters:
   • null as the first parameter, indicating that no KeyManager should be used.
   • trustAllCerts as the second parameter, indicating that all server certificates should be trusted.
   • SRAND as the third parameter, which is a SecureRandom object used for seed generation in the handshake process.
   • trustAllCerts is likely an array of TrustManager objects that implement a trust manager that trusts all certificates.
   • SRAND is likely a SecureRandom object that provides a cryptographically strong random number generator.
4. If any exception occurs during the creation or initialization of the SSLContext object, the context variable is set back to null.
5. Finally, the method returns the SSLContext object context, which may be null if any exception occurred.

Overall, the createOpenTLSContext method attempts to create and initialize an SSLContext object with the default SSL/TLS protocol and with trust in all server certificates. It is typically used for establishing a secure TLS connection in the NATS Java client library.

The createOpenTLSContext method in the SSLUtils class is used to create an SSLContext object for establishing a TLS connection.

Inside the method, it first calls SSLContext.getInstance method to create an SSLContext object with the default SSL protocol specified in the Options class.

Then, it initializes the SSLContext object by calling the init method with null as the TrustManager array, trustAllCerts as the TrustManager implementation (presumably, an array of all-trusting trust managers), and SRAND as the source of randomness.

If any exception occurs during the creation or initialization process, the SSLContext object will be set to null.

Finally, the method returns the created SSLContext object.

Overall, this method is responsible for creating and initializing an SSLContext object for TLS connections with the default SSL protocol.

DateTimeUtils

This class, DateTimeUtils, is an abstract class that provides internal json parsing helpers.

public static ZonedDateTime parseDateTime(String dateTime, ZonedDateTime dflt) {
    try {
        return toGmt(ZonedDateTime.parse(dateTime));
    } catch (DateTimeParseException s) {
        return dflt;
    }
}

The parseDateTime method is defined in the io.nats.client.support.DateTimeUtils class and is responsible for parsing a given dateTime string and returning a ZonedDateTime object. If the parsing fails, the method will return a default ZonedDateTime object specified by the dflt parameter.

• dateTime (String): The dateTime string to be parsed.
• dflt (ZonedDateTime): The default ZonedDateTime object to be returned if parsing fails.

• ZonedDateTime: A ZonedDateTime object representing the parsed date and time. If parsing fails, the default ZonedDateTime object will be returned.

1. Try to execute the following steps:

   • Parse the dateTime string using the ZonedDateTime.parse method.
   • Convert the parsed ZonedDateTime object to GMT time zone using the toGmt method.
   • Return the converted ZonedDateTime object.

2. If any DateTimeParseException occurs during the parsing process:

   • Catch the exception.
   • Return the default ZonedDateTime object specified by the dflt parameter.

The parseDateTime method in the DateTimeUtils class is a static method that takes a string representing a date and time, and returns a ZonedDateTime object. If the string cannot be parsed into a ZonedDateTime, it returns a default value provided as a parameter.

The method attempts to parse the dateTime string using the ZonedDateTime.parse method. If the parsing is successful, the resulting ZonedDateTime object is converted to GMT using the toGmt method (which is not shown in the code snippet). If the parsing fails and throws a DateTimeParseException, the method returns the default value dflt.

WebsocketOutputStream

The WebsocketOutputStream class is a public class that extends the OutputStream class. This class is used to handle output stream operations for websockets.

public void close() throws IOException

@Override
public void close() throws IOException {
    // NOTE: Per spec, we should technically wait to receive the close frame,
    // but we are not in control of the InputStream here...
    WebsocketFrameHeader header = new WebsocketFrameHeader().withOp(OpCode.CLOSE, true).withNoMask().withPayloadLength(0);
    int length = header.read(headerBuffer, 0, headerBuffer.length);
    wrap.write(headerBuffer, 0, length);
    wrap.close();
}

The close method in the WebsocketOutputStream class, defined in the io.nats.client.support package, is used to close the output stream for a WebSocket connection.

Here are the step-by-step description of what this method does:

1. The method overrides the close method from the superclass, which is java.io.OutputStream, and it throws an IOException.

2. Before closing the output stream, the method makes a note that, as per the WebSocket specification, ideally, it should wait to receive the close frame. However, since it is not in control of the input stream, it doesn't wait.

3. It creates a new instance of the WebsocketFrameHeader class.

4. The WebsocketFrameHeader instance is configured with the OpCode.CLOSE operation code, indicating that it wants to close the WebSocket connection. The second parameter true sets the "final" bit of the frame header to true, indicating that this frame represents the entire payload.

5. The WebsocketFrameHeader instance is further configured with the withNoMask method, which disables the masking of the payload. Masking is a security feature to prevent certain attacks, but in this case, it is not required, so it is disabled.

6. The payload length is set to 0 because it is an empty frame.

7. The header object reads the frame header data into a byte array called headerBuffer using the read method, which returns the length of the read data.

8. The wrap object, which represents the underlying output stream, writes the headerBuffer data to the stream using the write method. The length parameter specifies the number of bytes to write.

9. Finally, the wrap object's close method is called to close the underlying output stream, releasing any system resources associated with it.

Overall, this close method sends a close frame header with no payload length to indicate the intention to close the WebSocket connection and then closes the output stream.

The close method in the io.nats.client.support.WebsocketOutputStream class is responsible for closing the WebSocket output stream.

In the method, it first creates a WebSocket frame header with the CLOSE opcode and no payload. It then writes the header to the underlying output stream using the write method of the wrap object. Finally, it closes the wrap object, which will flush any remaining data and close the output stream.

It is important to note that according to the WebSocket specification, the method should technically wait to receive the close frame, but that is not possible in this context because the method has no control over the underlying input stream.

public void write(byte[] buffer, int offset, int length) throws IOException

@Override
public void write(byte[] buffer, int offset, int length) throws IOException {
    header.withPayloadLength(length);
    if (masked) {
        header.withMask(random.nextInt());
    }
    int headerBufferOffset = header.read(headerBuffer, 0, headerBuffer.length);
    int consumed = Math.min(length, headerBuffer.length - headerBufferOffset);
    System.arraycopy(buffer, offset, headerBuffer, headerBufferOffset, consumed);
    header.filterPayload(headerBuffer, headerBufferOffset, consumed);
    wrap.write(headerBuffer, 0, headerBufferOffset + consumed);
    if (consumed < length) {
        // NOTE: We could perform a "mark" operation before filtering the
        // payload which saves the payloadLength and maskingKeyOffset, then
        // perform a "resetMark" operation after writing the masked buffer
        // and finally re-applying the filter in order to preserve the
        // original values of the bytes. However, there appears to be no
        // code which relies on the bytes in the buffer to be preserved,
        // so we are keeping things efficient by not performing these
        // operations.
        header.filterPayload(buffer, offset + consumed, length - consumed);
        wrap.write(buffer, offset + consumed, length - consumed);
    }
}

The write(byte[] buffer, int offset, int length) method, defined in the WebsocketOutputStream class, is responsible for writing the specified portion of a byte array to the underlying output stream.

1. Set the length of the payload in the header.
2. If the payload is masked, generate a random mask and set it in the header.
3. Read the header into a buffer and calculate the offset.
4. Calculate the number of bytes to be consumed, which is the minimum of the length and the remaining space in the header buffer.
5. Copy the bytes from the input buffer to the header buffer.
6. Filter the payload bytes in the header buffer.
7. Write the header buffer to the underlying output stream.
8. If the number of consumed bytes is less than the length of the payload:
   • Filter the remaining payload bytes.
   • Write the remaining payload bytes to the underlying output stream.

The write method in the WebsocketOutputStream class is used to write data to a WebSocket connection.

This method takes in three parameters: buffer, offset, and length. The buffer parameter is the array of bytes to be written, the offset parameter is the starting index of the data to be written in the buffer, and the length parameter is the number of bytes to be written.

Within the method, the payloadLength of the WebSocket header is updated with the length of the data to be written. If the WebSocket is masked, a random mask value is generated and added to the header.

A portion of the data is then copied from the buffer to a headerBuffer, which is a buffer for the WebSocket header. The data in the headerBuffer is then filtered according to the WebSocket payload filtering rules.

After that, the filtered headerBuffer is written to the WebSocket connection using the wrap.write method.

If there is still remaining data in the original buffer after writing the headerBuffer, it is filtered and then written to the WebSocket connection using the wrap.write method again.

Note: There is a comment indicating that a more complex "mark" and "resetMark" operation could be performed to preserve the original values of the bytes in the buffer, but it is mentioned that there is no code relying on this preservation, so the more efficient approach is taken.

WebSocket

The WebSocket class is a public class that extends the Socket class. It provides functionality for handling communication over a WebSocket connection.

private static void handshake(Socket socket, String host, List<Consumer<HttpRequest>> interceptors) throws IOException {
    InputStream in = socket.getInputStream();
    OutputStream out = socket.getOutputStream();
    HttpRequest request = new HttpRequest();
    // The value of this header field MUST be a
    // nonce consisting of a randomly selected 16-byte value that has
    // been base64-encoded
    byte[] keyBytes = new byte[16];
    new SecureRandom().nextBytes(keyBytes);
    String key = Base64.getEncoder().encodeToString(keyBytes);
    request.getHeaders().add("Host", host).add("Upgrade", "websocket").add("Connection", "Upgrade").add("Sec-WebSocket-Key", key).add("Sec-WebSocket-Protocol", "nats").add("Sec-WebSocket-Version", "13");
    // TODO: Support Sec-WebSocket-Extensions: permessage-deflate
    // TODO: Support Nats-No-Masking: TRUE
    for (Consumer<HttpRequest> interceptor : interceptors) {
        interceptor.accept(request);
    }
    out.write(request.toString().getBytes(UTF_8));
    // rfc6455 4.1 "The client MUST validate the server's response as follows:"
    byte[] buffer = new byte[MAX_LINE_LEN];
    String responseLine = readLine(buffer, in);
    if (null == responseLine) {
        throw new IllegalStateException("Expected HTTP response line not to exceed " + MAX_LINE_LEN);
    }
    // 1. expect 101:
    if (!responseLine.toLowerCase().startsWith(WEBSOCKET_RESPONSE_LINE.toLowerCase())) {
        throw new IllegalStateException("Expected " + WEBSOCKET_RESPONSE_LINE + ", but got " + responseLine);
    }
    Map<String, String> headers = new HashMap<>();
    while (true) {
        String line = readLine(buffer, in);
        if (null == line) {
            throw new IllegalStateException("Expected HTTP header to not exceed " + MAX_LINE_LEN);
        }
        if ("".equals(line)) {
            break;
        }
        int colon = line.indexOf(':');
        if (colon >= 0) {
            if (headers.size() >= MAX_HTTP_HEADERS) {
                throw new IllegalStateException("Exceeded max HTTP headers=" + MAX_HTTP_HEADERS);
            }
            headers.put(line.substring(0, colon).trim().toLowerCase(), line.substring(colon + 1).trim());
        } else {
            throw new IllegalStateException("Expected HTTP header to contain ':', but got " + line);
        }
    }
    // 2. Expect `Upgrade: websocket`
    if (!"websocket".equalsIgnoreCase(headers.get("upgrade"))) {
        throw new IllegalStateException("Expected HTTP `Upgrade: websocket` header");
    }
    // 3. Expect `Connection: Upgrade`
    if (!"upgrade".equalsIgnoreCase(headers.get("connection"))) {
        throw new IllegalStateException("Expected HTTP `Connection: Upgrade` header");
    }
    // 4. Sec-WebSocket-Accept: base64(sha1(key + "258EAF..."))
    MessageDigest sha1;
    try {
        sha1 = MessageDigest.getInstance("SHA-1");
    } catch (NoSuchAlgorithmException ex) {
        throw new IllegalStateException(ex);
    }
    sha1.update(key.getBytes(UTF_8));
    sha1.update("258EAFA5-E914-47DA-95CA-C5AB0DC85B11".getBytes(UTF_8));
    String acceptKey = Base64.getEncoder().encodeToString(sha1.digest());
    String gotAcceptKey = headers.get("sec-websocket-accept");
    if (!acceptKey.equals(gotAcceptKey)) {
        throw new IllegalStateException("Expected HTTP `Sec-WebSocket-Accept: " + acceptKey + ", but got " + gotAcceptKey);
    }
    // 5 & 6 are not valid, since nats-server doesn't
    // implement extensions or protocols.
}

The handshake method is defined in the io.nats.client.support.WebSocket class, and it is responsible for establishing a WebSocket connection between the client and the server.

1. Create an input stream from the socket to receive data from the server.
2. Create an output stream from the socket to send data to the server.
3. Create an instance of HttpRequest.
4. Generate a 16-byte random value and encode it in base64 format to create a nonce.
5. Set the necessary headers in the request, including "Host", "Upgrade", "Connection", "Sec-WebSocket-Key", "Sec-WebSocket-Protocol", and "Sec-WebSocket-Version".
6. Optionally, support additional headers using the provided interceptors.
7. Convert the request into a byte array and write it to the output stream.

1. Define a byte buffer to read data from the input stream.
2. Read the response line from the input stream.
3. Ensure that the response line does not exceed the maximum line length.
4. Verify that the response line starts with "HTTP/1.1 101" to indicate a successful upgrade to WebSocket.
5. Create a map to store the HTTP headers.
6. Read each header line from the input stream until an empty line is encountered.
7. Ensure that each header line does not exceed the maximum line length.
8. Split each header line by the colon (":") character to separate the header name and value.
9. Store the header name and value in the map, converting the header name to lowercase.
10. Ensure that the number of headers does not exceed the maximum allowed limit.

1. Verify that the "Upgrade" header is set to "websocket".
2. Verify that the "Connection" header is set to "Upgrade".

1. Create an instance of MessageDigest using the SHA-1 algorithm.
2. Update the digest with the base64-encoded nonce and a constant string.
3. Generate the expected accept key by encoding the digest into base64 format.
4. Retrieve the received accept key from the headers.
5. Ensure that the received accept key matches the expected accept key.

The server does not support Sec-WebSocket-Extensions or Sec-WebSocket-Protocol, so these steps are skipped.

The server does not support Sec-WebSocket-Extensions or Sec-WebSocket-Protocol, so these steps are skipped.

The handshake method in the io.nats.client.support.WebSocket class is responsible for performing the handshake process between the client and server when establishing a WebSocket connection.

Here is a breakdown of what the method does:

1. Creates an HttpRequest object and sets the necessary headers for the handshake.
2. Invokes any interceptors that have been registered with the method.
3. Writes the request string to the output stream of the socket.
4. Reads the response line from the input stream and checks that it starts with the expected response code "101".
5. Parses the HTTP headers from the response and checks that the "Upgrade" and "Connection" headers are set to "websocket" and "upgrade" respectively.
6. Calculates the accept key for the "Sec-WebSocket-Accept" header by hashing the generated key with a predefined value and encoding it to Base64.
7. Verifies that the received "Sec-WebSocket-Accept" header value matches the calculated accept key.
8. Performs additional checks that are not currently used by the nats-server implementation.

Overall, the handshake method ensures that the server accepts the WebSocket connection by validating the response and headers received during the handshake process.

private static String readLine(byte[] buffer, InputStream in) throws IOException {
    int offset = 0;
    int lastCh = -1;
    while (true) {
        int ch = in.read();
        switch(ch) {
            case -1:
                // Premature EOF (everything should be terminated with \n)
                return new String(buffer, 0, offset, StandardCharsets.ISO_8859_1);
            case '\n':
                // Found \n, remove \r if it is there:
                return new String(buffer, 0, '\r' == lastCh ? offset - 1 : offset, StandardCharsets.ISO_8859_1);
        }
        // Line length exceeded:
        if (offset >= buffer.length) {
            return null;
        }
        buffer[offset++] = (byte) ch;
        lastCh = ch;
    }
}

The readLine method in the WebSocket class is used to read a line from an input stream. It takes a byte array called buffer and an input stream called in as parameters.

Here is a step-by-step description of what the method does:

1. Initialize variables:

   • offset is set to 0, which represents the current index in the buffer array.
   • lastCh is set to -1, which represents the last character read from the input stream.

2. Enter an infinite loop:

   • This loop will continue until the method explicitly returns a value.

3. Read a character from the input stream:

   • The in.read() method is called to read the next character from the input stream.
   • The character is stored in the variable ch.

4. Process the character:

   • The method uses a switch statement to check the value of ch.

   • If ch is -1:

     • This indicates that the end of the input stream has been reached (premature EOF).
     • The method constructs a new string using the buffer array, from index 0 to offset, using the ISO-8859-1 character encoding.
     • The constructed string is returned as the result of the method.

   • If ch is '\n' (newline character):

     • This indicates that a complete line has been read.
     • The method constructs a new string using the buffer array, from index 0 to offset, using the ISO-8859-1 character encoding.
     • If the last character read (lastCh) is '\r' (carriage return character), it means that the line might contain a Windows-style line ending.
       • In this case, the method subtracts 1 from offset to remove the '\r' character from the line.
     • The constructed string is returned as the result of the method.

   • If none of the above conditions are met (line length exceeded):

     • The method checks if the offset is greater than or equal to the length of the buffer array.
     • If the condition is true, the method returns null to indicate that the line length has exceeded the buffer size.

5. Store the read character in the buffer array:

   • The read character is cast to a byte and stored in the buffer array at the current offset index.
   • The offset is then incremented.

6. Update the lastCh variable:

   • The lastCh variable is updated with the value of the current character (ch).

7. Repeat the loop to read the next character from the input stream.

Note: The method assumes that the input stream contains lines terminated with either '\n' or '\r\n' characters.

The readLine method is used to read a line of text from an input stream in the context of a WebSocket. It takes in a byte[] buffer and an InputStream as parameters.

The method reads characters from the input stream until it encounters either the end of the stream or a line break character ('\n'). If it reaches the end of the stream, it returns the contents of the buffer as a string.

If it encounters a line break character, it checks if the previous character was a carriage return character ('\r'). If so, it removes it from the buffer before returning the contents as a string.

If the line length exceeds the size of the buffer, the method returns null.

The method uses the StandardCharsets.ISO_8859_1 character encoding when converting the buffer to a string.

RandomUtils

The RandomUtils class is an abstract class that provides various utility methods for generating random values. It is designed to be extended by concrete classes, which can then access these random utility methods to generate random numbers, strings, and other types of values. This class serves as a convenient tool for developers who need to incorporate randomization into their software applications.

public static long nextLong(Random rng, long maxValue) {
    // error checking and 2^x checking removed for simplicity.
    long bits;
    long val;
    do {
        bits = (rng.nextLong() << 1) >>> 1;
        val = bits % maxValue;
    } while (bits - val + (maxValue - 1) < 0L);
    return val;
}

The nextLong method, defined in the io.nats.client.support.RandomUtils class, generates a random long integer value within a specified range.

public static long nextLong(Random rng, long maxValue)

• rng: A Random object used for generating random numbers.
• maxValue: The upper bound (exclusive) of the range within which the random long value should be generated.

1. Error checking and checking whether maxValue is a power of 2 are removed for simplicity.
2. Declare two long variables, bits and val, to store the generated random bits and the final random value, respectively.
3. Start a do-while loop that will run until a suitable random value is found.
4. Generate random bits using the nextLong() method of the rng object and store them in the bits variable.
5. Shift the bits one position to the left and then one position back to the right using the bitwise left shift (<<) and the bitwise right shift (>>>) operators, respectively. This operation is performed to ensure that the bits value is non-negative (signed shift right operator preserves the sign bit).
6. Calculate the remainder of dividing bits by maxValue and store it in the val variable. This will give a random value within the range [0, maxValue).
7. Check if the difference between bits, val, and maxValue - 1 is less than 0L. If the condition is true, it means that the generated value is larger than maxValue - 1, which would create a bias towards smaller values. In this case, the loop repeats to generate a new random value.
8. If the condition in step 7 is false, the loop is exited, and the val variable containing the randomly generated value is returned as the result of the method.

The method nextLong in the class io.nats.client.support.RandomUtils generates a pseudo-random long value within a specified range.

The method takes two parameters: rng, which is an instance of the Random class used to generate the random values, and maxValue, which represents the upper bound of the range (exclusive).

Inside the method, the logic is as follows:

1. Generate a random long value using the provided rng instance.
2. Shift the generated value one bit to the left and then one bit to the right, effectively clearing the sign bit.
3. Calculate the remainder of dividing the resulting value by maxValue to bring it within the specified range.
4. Repeat steps 1-3 until a valid value is obtained, satisfying the condition bits - val + (maxValue - 1) < 0L.
5. Return the generated value.

This method provides a way to generate random long values within a given range using the provided random number generator.

public static long bytesToLong(byte[] bytes) {
    ByteBuffer buffer = ByteBuffer.allocate(Long.SIZE);
    buffer.put(bytes);
    // need flip
    buffer.flip();
    return buffer.getLong();
}

The bytesToLong method is a static method defined in the io.nats.client.support.RandomUtils class. The method takes in a byte array as a parameter and converts it into a long value. Here is a step-by-step description of what the method does:

1. Allocate a new ByteBuffer with the capacity equivalent to Long.SIZE. This means the buffer will have enough space to hold a long value.

2. Copy the contents of the bytes parameter into the buffer using the put method. This will fill the buffer with the bytes from the byte array.

3. Call the flip method on the buffer. This method is used to prepare the buffer for reading. It sets the buffer's limit to the current position and resets the position to 0.

4. Retrieve the long value from the buffer using the getLong method. This method reads eight bytes from the buffer and interprets them as a long value.

5. Return the long value.

In summary, the bytesToLong method takes a byte array, copies it into a ByteBuffer, flips the buffer to prepare it for reading, and then retrieves a long value from the buffer.

The bytesToLong method in the io.nats.client.support.RandomUtils class is a utility method that converts a byte array to a long value.

Here's how it works:

1. The method takes a byte array (bytes) as input.
2. It creates a ByteBuffer object with a size of Long.SIZE (which is the size of a long value in bits).
3. The byte array is then copied into the ByteBuffer using the put method.
4. The flip method is called on the ByteBuffer to prepare it for reading.
5. Finally, the getLong method is called on the ByteBuffer to retrieve the long value.

In summary, the bytesToLong method allows you to convert a byte array to a long value using the ByteBuffer class.

Digester

The Digester class is a utility class for making digesting data. It provides methods that can be used to compute digests of data using various algorithms.

public boolean matches(String digestEntry) {
    String algo = digest.getAlgorithm().toUpperCase();
    if (!digestEntry.toUpperCase().startsWith(algo)) {
        return false;
    }
    // + 1 for equals
    return getDigestValue().equals(digestEntry.substring(algo.length() + 1));
}

This method is defined in the class io.nats.client.support.Digester and takes a String parameter named digestEntry. It returns a boolean value.

• digestEntry: The digest entry that needs to be matched.

• The method starts by converting the algorithm of the digest object (assuming it is an instance variable in the class) to uppercase using the toUpperCase() method.
• It then checks if the digestEntry string starts with the uppercase algorithm string. If it doesn't, the method returns false.
• If the digestEntry string does start with the algorithm string, the method compares the digest value obtained from the getDigestValue() method (assuming it is a method in the same class) with the substring of digestEntry obtained by removing the algorithm string plus one additional character (to remove the space after the algorithm).
• If the digest value and the substring match, the method returns true. Otherwise, it returns false.

The matches method in the Digester class is used to check whether a given digestEntry string matches the expected algorithm and digest value.

The method first compares the starting characters of the digestEntry string with the uppercase value of the algorithm used to generate the digest. If they do not match, the method returns false.

If the starting characters match, the method then extracts the substring after the algorithm name and checks if it is equal to the expected digest value by calling the getDigestValue() method. If the extracted digest value matches the expected value, the method returns true, indicating a successful match.

Overall, this method provides a way to verify if a given digest entry matches the expected algorithm and digest value.

IncomingHeadersProcessor

The IncomingHeadersProcessor class is a public class that is responsible for processing incoming headers. It handles the processing of headers that are received by the software application.

private void initHeader(byte[] serialized, int len, Token tCrlf, boolean hadStatus) {
    // REGULAR HEADER
    Token peek = new Token(serialized, len, tCrlf, null);
    while (peek.isType(TokenType.TEXT)) {
        Token tKey = new Token(serialized, len, tCrlf, TokenType.KEY);
        Token tVal = new Token(serialized, len, tKey, null);
        if (tVal.isType(TokenType.SPACE)) {
            tVal = new Token(serialized, len, tVal, null);
        }
        if (tVal.isType(TokenType.TEXT)) {
            tCrlf = new Token(serialized, len, tVal, TokenType.CRLF);
        } else {
            tVal.mustBe(TokenType.CRLF);
            tCrlf = tVal;
        }
        if (headers == null) {
            headers = new Headers();
        }
        headers.add(tKey.getValue(), tVal.getValue());
        peek = new Token(serialized, len, tCrlf, null);
    }
    peek.mustBe(TokenType.CRLF);
}

The initHeader method in class io.nats.client.support.IncomingHeadersProcessor is responsible for initializing the headers based on the provided serialized byte array.

Here is a step-by-step description of what the method does:

1. Initialize a Token object peek with the provided serialized byte array, length, and a token of type tCrlf.

2. Start a while loop that iterates as long as the peek token is of type TEXT.

3. Within the loop, create a new Token object tKey with the same parameters as peek, but with a token type of KEY.

4. Create a new Token object tVal with the same parameters as tKey, but with a null token type.

5. Check if tVal is of type SPACE. If it is, create a new Token object tVal using the current tVal as the base token and null as the token type.

6. Check if tVal is of type TEXT. If it is, create a new Token object tCrlf using the current tVal as the base token and a token type of CRLF. Otherwise, tVal must be of type CRLF, so set tCrlf to tVal.

7. Check if the headers object is null. If it is, initialize a new Headers object.

8. Add the key-value pair represented by tKey and tVal to the headers object.

9. Update the peek token to the next token in the array by creating a new Token object with the same parameters as tCrlf, but with a token type of null.

10. Check that the peek token is of type CRLF. If it is not, an exception is thrown.

11. Repeat the loop until the peek token is not of type TEXT.

Once the loop finishes, the method will have processed all the headers in the serialized byte array and stored them in the headers object.

The initHeader method is used to initialize the headers of a message. It takes in a serialized byte array, its length, a token representing the carriage return line feed (CRLF), and a boolean indicating whether the message had a status.

The method processes the serialized header information by iterating over the tokens. It starts by creating a peek token and checks if it is of type TEXT. If it is, it creates a tKey token representing the key of the header using the serialized byte array, its length, and the CRLF token.

Next, it creates a tVal token representing the value of the header. If the tVal token is of type SPACE, it creates a new token without a parent to eliminate the space.

Then, it checks if the tVal token is of type TEXT or CRLF. If it is TEXT, it sets the CRLF token to a new token with the tVal token as its parent. If it is CRLF, it sets the CRLF token to the tVal token itself.

If the headers object is null, it creates a new Headers object.

Finally, it adds the key-value pair to the headers object, and updates the peek token to continue processing the next token. This process continues until the peek token is of type CRLF.

The method ensures that the last token must be of type CRLF.

private Token initStatus(byte[] serialized, int len, Token tSpace) {
    Token tCode = new Token(serialized, len, tSpace, TokenType.WORD);
    Token tVal = new Token(serialized, len, tCode, null);
    Token crlf;
    if (tVal.isType(TokenType.SPACE)) {
        tVal = new Token(serialized, len, tVal, TokenType.TEXT);
        crlf = new Token(serialized, len, tVal, TokenType.CRLF);
    } else {
        tVal.mustBe(TokenType.CRLF);
        crlf = tVal;
    }
    inlineStatus = new Status(tCode, tVal);
    return crlf;
}

The initStatus method in the IncomingHeadersProcessor class is responsible for initializing the status of the incoming headers based on the provided byte[] serialized data.

Here is a step-by-step description of what the method does:

1. The method takes in three parameters: serialized (the byte array containing the serialized data), len (the length of the serialized data), and tSpace (a token object of type Token).

2. It creates a new token object tCode using the serialized, len, tSpace, and TokenType.WORD. The tCode token represents the code of the status.

3. It creates a new token object tVal using the serialized, len, tCode, and null. Initially, tVal is set to null.

4. It creates a new token object crlf to represent the carriage return line feed (CRLF) characters. The value of crlf will depend on the type of tVal.

5. If tVal is of type TokenType.SPACE, it means that there is a space character between the status code and the status value. In this case, tVal is replaced with a new token object created using the serialized, len, tVal, and TokenType.TEXT. Then, crlf is set to a new token object created using the serialized, len, tVal, and TokenType.CRLF.

6. If tVal is not of type TokenType.SPACE, it means that there is no space character between the status code and the status value. In this case, tVal must be of type TokenType.CRLF, and crlf is set to tVal.

7. A new Status object is created using the tCode and tVal tokens, and assigned to the inlineStatus member variable.

8. Finally, the method returns the crlf token.

This method essentially parses the serialized data, extracts the status code and value, creates a Status object, and returns the token representing the CRLF characters.

The initStatus method in the IncomingHeadersProcessor class takes in a byte array, its length, and a Token object as parameters. It initializes and sets the inlineStatus variable by creating a new Status object with tCode and tVal as its parameters. It then returns a Token object named crlf.

NatsKeyValueUtil

The NatsKeyValueUtil class is an abstract class designed to provide utility methods for working with key-value stores in the Nats system. This class serves as a base for other classes that implement specific functionality for different types of key-value stores.

public static String trimPrefix(String bucketName) {
    if (bucketName.startsWith(KV_STREAM_PREFIX)) {
        return bucketName.substring(KV_STREAM_PREFIX.length());
    }
    return bucketName;
}

The trimPrefix method is defined in the io.nats.client.support.NatsKeyValueUtil class and is used to remove a specific prefix string from the beginning of a given bucketName string.

public static String trimPrefix(String bucketName)

• bucketName - The string from which the prefix needs to be removed.

• String - The modified bucketName string after removing the prefix.

1. Check if the bucketName starts with the prefix string KV_STREAM_PREFIX.
2. If it starts with the prefix, then remove the prefix from the bucketName string by using the substring method with the index length of the KV_STREAM_PREFIX.
3. Return the modified bucketName string without the prefix.
4. If the bucketName does not start with the prefix, then simply return the bucketName as it is.

public static String trimPrefix(String bucketName) {
    if (bucketName.startsWith(KV_STREAM_PREFIX)) {
        return bucketName.substring(KV_STREAM_PREFIX.length());
    }
    return bucketName;
}

The method trimPrefix in class NatsKeyValueUtil is a utility method that takes a String parameter bucketName and returns the bucketName with the prefix removed if it starts with the constant KV_STREAM_PREFIX.

If the bucketName starts with the KV_STREAM_PREFIX, the method returns the portion of the bucketName that comes after the KV_STREAM_PREFIX by using the substring method.

If the bucketName does not start with the KV_STREAM_PREFIX, the method simply returns the original bucketName.

ByteArrayBuilder

ByteArrayBuilder is a public class that extends BuilderBase. It is used to efficiently build byte arrays.

public int copyTo(byte[] dest, int destPos) {
    int len = length();
    byte[] hb = buffer.array();
    System.arraycopy(hb, 0, dest, destPos, len);
    return len;
}

The copyTo method in the io.nats.client.support.ByteArrayBuilder class is responsible for copying the contents of the internal buffer to a specified destination array.

Here is a step-by-step description of what the method does:

1. Retrieve the length of the internal buffer using the length() method.

2. Access the underlying byte array by calling buffer.array(), where buffer is an instance variable of type ByteBuffer.

3. Use the System.arraycopy() method to copy the bytes from the internal buffer to the destination array. The source array is hb (the underlying byte array) and the starting position in the source array is 0. The destination array is dest, and the starting position in the destination array is destPos. The number of bytes to copy is len (the length of the internal buffer).

4. Return the length of the copied data.

Please note that this description assumes that you have already imported the required classes and have instantiated an object of the ByteArrayBuilder class.

The copyTo method in the ByteArrayBuilder class, defined in the io.nats.client.support package, is used to copy the contents of the builder's internal buffer to a destination byte array.

The method takes two parameters: dest, which is the destination byte array where the contents will be copied to, and destPos, which is the starting position in the destination byte array where the copying will begin.

The method first retrieves the length of the data in the builder using the length method. Then, it accesses the internal buffer of the builder using the buffer.array() method and assigns it to the hb variable.

Finally, using the System.arraycopy() method, it copies the contents of the internal buffer (hb) to the specified destination byte array (dest) starting at the given position (destPos) and copied data length (len). The method then returns the length of the copied data.

In summary, the copyTo method allows you to efficiently copy the contents of the ByteArrayBuilder to a destination byte array, starting from a specified position.

public ByteArrayBuilder ensureCapacity(int bytesNeeded) {
    int bytesAvailable = buffer.capacity() - buffer.position();
    if (bytesAvailable < bytesNeeded) {
        ByteBuffer newBuffer = ByteBuffer.allocate(bufferAllocSize(buffer.position() + bytesNeeded, allocationSize));
        newBuffer.put(buffer.array(), 0, buffer.position());
        buffer = newBuffer;
    }
    return this;
}

The ensureCapacity method in the ByteArrayBuilder class defined in the io.nats.client.support package is used to ensure that the internal buffer has enough capacity to hold the specified number of bytes.

Here is a step-by-step description of what the method does:

1. Get the number of bytes available in the buffer by subtracting the current position from the total capacity of the buffer.

2. Check if the number of bytes available is less than the number of bytes needed.

3. If the condition in step 2 is true, create a new ByteBuffer with a capacity calculated based on the current position of the buffer and the number of bytes needed.

4. Copy the content of the existing buffer into the new buffer up to the current position.

5. Set the internal buffer reference to the new buffer.

6. Return a reference to the ByteArrayBuilder object to allow method chaining.

This method ensures that the ByteArrayBuilder has enough capacity to hold the specified number of bytes by creating a new buffer if necessary and copying the existing content into the new buffer.

The ensureCapacity method in the ByteArrayBuilder class is used to ensure that the buffer used by the ByteArrayBuilder has enough capacity to accommodate the specified number of bytes.

The method first calculates the number of bytes available in the current buffer by subtracting the buffer's position from its capacity. If the available capacity is less than the requested number of bytes, a new buffer is allocated with an increased size using the bufferAllocSize method.

The contents of the existing buffer are then copied into the new buffer, and the reference to the new buffer is assigned to the buffer field of the ByteArrayBuilder. Finally, the method returns a reference to the ByteArrayBuilder object itself.

In summary, the ensureCapacity method ensures that the ByteArrayBuilder has enough capacity to accommodate the requested number of bytes by reallocating a larger buffer if necessary.

public ByteArrayBuilder append(CharBuffer src, Charset charset) {
    if (src == null) {
        append(NULL, 0, 4);
    } else {
        append(src.toString().getBytes(charset));
    }
    return this;
}

The append method in the ByteArrayBuilder class is used to add data to the builder's internal byte array.

Here is a step-by-step description of what the method does based on its body:

1. It takes two parameters: src, which is a CharBuffer containing the data to be appended, and charset, which is the character set used for encoding the data.

2. If the src parameter is null, it calls the append method of the ByteArrayBuilder class with the following parameters:

   • The NULL constant, which is a reference to a byte array representing the value null.
   • The offset (0), which specifies the starting index in the byte array.
   • The length (4), which indicates the number of bytes to be copied from the byte array.

3. If the src parameter is not null, it converts the CharBuffer to a String by calling its toString method, and then gets the byte representation of the string using the specified charset encoding. This byte array is then passed to the overloaded append method of the ByteArrayBuilder class.

4. After appending the data to the builder's internal byte array, the method returns a reference to the ByteArrayBuilder object itself, enabling method chaining.

Overall, the append method allows you to add data to the ByteArrayBuilder by providing a CharBuffer or a String object, and it takes care of converting the data to bytes using the specified character encoding.

The append method in the ByteArrayBuilder class of the io.nats.client.support package is used to add characters from a CharBuffer to the byte array.

First, it checks if the src (CharBuffer) is null. If it is, it appends NULL to the byte array. Otherwise, it converts the CharBuffer to a string using the specified charset and converts that string to bytes. Finally, it appends the resulting byte array to the existing byte array.

After performing these operations, the append method returns a reference to the current ByteArrayBuilder object, allowing for method chaining.

public ByteArrayBuilder append(byte[] src) {
    if (src.length > 0) {
        ensureCapacity(src.length);
        buffer.put(src, 0, src.length);
    }
    return this;
}

The append method in the ByteArrayBuilder class is used to append a byte array to the existing builder object. Here is a step-by-step description of what the method does:

1. Check if the length of the provided byte array (src) is greater than zero.
2. If the length is greater than zero, proceed to the next step. Otherwise, return the current builder object.
3. Call the ensureCapacity method to ensure that the internal buffer of the builder has enough space to accommodate the new bytes being appended.
4. Use the put method to copy the bytes from the src array into the internal buffer of the builder, starting from index 0 and copying src.length number of bytes.
5. Finally, return the updated builder object.

Note: The ensureCapacity method is not provided in the given code snippet. It is assumed to handle the resizing of the internal buffer to accommodate the new bytes if necessary.

The append method in the ByteArrayBuilder class (defined in io.nats.client.support) allows you to append a byte array to the existing byte array builder.

This method takes in a byte[] parameter named src. It first checks if the length of the src array is greater than zero. If it is, it ensures that the builder has enough capacity to accommodate the new byte array by calling the ensureCapacity method.

Finally, it uses the put method of the internal buffer to copy the content of the src array to the builder's buffer starting from index 0.

After appending the src array, the method returns a reference to the same ByteArrayBuilder object, allowing method chaining.

public ByteArrayBuilder append(byte[] src, int len) {
    if (len > 0) {
        ensureCapacity(len);
        buffer.put(src, 0, len);
    }
    return this;
}

The append method in the ByteArrayBuilder class of the io.nats.client.support package is used to append a byte array to the buffer managed by the ByteArrayBuilder object.

Here is a step-by-step description of what the append method does:

1. Check if the given length len is greater than zero. If it is not, the method does nothing and returns the current ByteArrayBuilder object.

2. If the length len is greater than zero, the method proceeds to the next step.

3. Ensure that the buffer has enough capacity to accommodate the additional data. If the current capacity of the buffer is not sufficient, it will be increased to meet the required capacity.

4. Copy the first len bytes from the source byte array src into the buffer managed by the ByteArrayBuilder object. The put method of the buffer is used for this purpose.

5. The method returns the current ByteArrayBuilder object, which allows for method chaining.

In summary, the append method appends a specified number of bytes from a given byte array to the buffer managed by the ByteArrayBuilder object, ensuring that the buffer has enough capacity to hold the data.

The append method defined in the ByteArrayBuilder class in the io.nats.client.support package is used to append bytes from a source byte array into the ByteArrayBuilder object. The method takes two parameters: src, which is the source byte array, and len, which specifies the number of bytes to append from the source array.

The method first checks if the len value is greater than 0, indicating that there are bytes to be appended. If len is greater than 0, the method ensures that the ByteArrayBuilder has enough capacity to accommodate the additional bytes.

Finally, the method uses the put method of the internal buffer object to append the specified number of bytes from the source array into the ByteArrayBuilder.

The method returns the updated ByteArrayBuilder object, allowing for chained method calls if needed.

public ByteArrayBuilder append(byte[] src, int offset, int len) {
    if (len > 0) {
        ensureCapacity(len);
        buffer.put(src, offset, len);
    }
    return this;
}

The append method in the io.nats.client.support.ByteArrayBuilder class is used to add a specified portion of a byte array to the current buffer.

Here is a step by step description of what the method does:

1. Check if the specified length (len) is greater than 0.
2. If the length is greater than 0, proceed to the next step.
3. Call the ensureCapacity method to make sure that the buffer has enough capacity to accommodate the specified length.
4. Use the put method of the buffer to copy the specified portion of the source byte array (src) into the buffer. The offset and length of the portion to be copied are specified by the offset and len parameters.
5. Return a reference to the current instance of the ByteArrayBuilder to allow for method chaining.

Overall, the append method appends a portion of a byte array to the buffer and returns a reference to the ByteArrayBuilder.

The append method, defined in the ByteArrayBuilder class of the io.nats.client.support package, is used to append a specified portion of a byte array to the existing byte array held by the builder.

The method takes three arguments: src (the source byte array from which the portion needs to be appended), offset (the starting index in the source array from where the portion begins), and len (the length of the portion to be appended).

First, the method checks if the length of the portion to be appended is greater than zero. If it is, the method proceeds to ensure that the builder's internal buffer has enough capacity to accommodate the new portion. If necessary, the buffer's size is increased.

Finally, the portion of the source byte array specified by the offset and len arguments is copied into the builder's buffer using the put method. The builder's reference is then returned.

In summary, the append method is responsible for appending a specified portion of a byte array to the byte array held by the builder, ensuring capacity if needed.

public ByteArrayBuilder append(ByteArrayBuilder bab) {
    if (bab != null && bab.length() > 0) {
        append(bab.buffer.array(), 0, bab.length());
    }
    return this;
}

The append method in the ByteArrayBuilder class is used to concatenate the contents of another ByteArrayBuilder object to the current object.

Here are the steps performed by this method:

1. Check if the provided ByteArrayBuilder object, bab, is not null and has a length greater than 0.
2. If bab is not null and has a length greater than 0: a. Retrieve the buffer array from bab using bab.buffer.array(). b. Call the append method of the current ByteArrayBuilder object, passing the buffer array, a starting index of 0, and the length of bab as parameters.
3. Return the current ByteArrayBuilder object.

In summary, this append method adds the contents of another ByteArrayBuilder object to the current object, as long as the provided ByteArrayBuilder is not null and has a non-zero length.

The append method in the ByteArrayBuilder class in the io.nats.client.support package is used to append the contents of another ByteArrayBuilder object to the current ByteArrayBuilder object.

In the method, it first checks if the bab object is not null and if it has a length greater than zero. If these conditions are met, it calls the append method again with the byte array, start index, and length of the bab object. This effectively appends the contents of bab to the current ByteArrayBuilder.

Finally, it returns the current ByteArrayBuilder object, allowing for method chaining if desired.

NatsObjectStoreUtil

NatsObjectStoreUtil is an abstract class representing a utility for interacting with an object store in the context of a Nats system. This class provides methods for managing and manipulating objects within the store, allowing software engineers to efficiently store and retrieve data.

WebsocketInputStream

The WebsocketInputStream class is a Java class that extends the InputStream class. It provides a specialized input stream for handling WebSocket connections. With this class, you can read data from a WebSocket connection as if it were a regular input stream.

public int read(byte[] buffer, int offset, int length) throws IOException

@Override
public int read(byte[] buffer, int offset, int length) throws IOException {
    // Just in case we get headers with empty payloads:
    while (0 == header.getPayloadLength()) {
        if (!readHeader()) {
            return -1;
        }
    }
    if (header.getOpCode() == OpCode.CLOSE) {
        // Ignore the websocket close message body:
        in.skip(header.getPayloadLength());
        return -1;
    }
    final long headerPayloadLength = header.getPayloadLength();
    final int payloadLength = Math.min(length, headerPayloadLength > Integer.MAX_VALUE ? Integer.MAX_VALUE : (int) headerPayloadLength);
    length = in.read(buffer, offset, payloadLength);
    if (-1 == length) {
        return length;
    }
    return header.filterPayload(buffer, offset, length);
}

The read method in the io.nats.client.support.WebsocketInputStream class is used to read data from a WebSocket connection. Here is a step-by-step description of what this method does based on its body:

1. Check if the payload length in the header is zero. This is done in a while loop to handle the case where headers with empty payloads are received. If the payload length is zero, it means there is no data to read and the next header is fetched.

2. If the operation code in the header is CLOSE, it means it is a WebSocket close message. In this case, the method skips the length specified in the header, ignoring the close message body, and returns -1 to indicate the end of the stream.

3. Get the payload length from the header and determine the length of the data to be read. This length is the minimum of the specified length parameter and the payload length, considering the maximum value of an integer.

4. Invoke the read method of the underlying input stream (in) to read the data into the given buffer, starting at the specified offset, and up to the determined payload length. The actual number of bytes read is stored in the length variable.

5. Check if the end of the stream has been reached. If the value returned by the read method is -1, it means no more data can be read and the method returns -1.

6. Filter the payload using the filterPayload method in the header. This method applies any filtering or transformations to the payload before returning it.

7. Finally, the method returns the filtered payload length.

This read method handles the reading of WebSocket data, excluding the header and any close message, and applies any necessary payload filtering before returning the data.

The read method in the WebsocketInputStream class is responsible for reading data from the input stream of a WebSocket connection.

Here are the steps performed by the method:

1. It checks if the headers have empty payloads. If so, it continues reading the headers until a non-empty payload is found.
2. If the OpCode of the header is CLOSE, it skips the WebSocket close message body and returns -1 to indicate the end of the stream.
3. It determines the payload length based on the smaller of the provided length or the header's payload length. If the header's payload length is greater than Integer.MAX_VALUE, it sets the payload length to Integer.MAX_VALUE.
4. It reads data from the underlying input stream in into the provided buffer starting from the specified offset and up to the determined payload length.
5. If the read length is -1, it indicates the end of the stream and returns -1.
6. Finally, it applies a filter to the payload in the buffer, starting from the specified offset and with the read length, using the header.filterPayload method. The filtered payload is returned as the result of the read method.

public int read() throws IOException

@Override
public int read() throws IOException {
    int result = read(oneByte, 0, 1);
    if (-1 == result) {
        return result;
    }
    return oneByte[0];
}

The read() method in the WebsocketInputStream class, located in the io.nats.client.support package, is used to read bytes from the websocket input stream.

Here is a step-by-step description of what the method is doing:

1. The method overrides the read() method from the InputStream class and indicates that it can throw an IOException.

2. In the method, a variable named result is declared to hold the result of the next step.

3. The read() method is called on the WebsocketInputStream object, passing in the oneByte array, starting at index 0, and specifying the number of bytes to read as 1. This method call reads one byte from the websocket input stream and stores it in the oneByte array.

4. The result variable is assigned the value returned by the read() method. If the value is equal to -1, it signifies the end of the stream has been reached, so the result is returned.

5. If the result is not equal to -1, the method returns the first element of the oneByte array, which represents the byte that was read.

In summary, the read() method reads one byte from the websocket input stream, stores it in the oneByte array, and returns that byte. If the end of the stream is reached, it returns -1.

This method, read, is an override of the read method defined in the WebsocketInputStream class in the io.nats.client.support package.

The purpose of this method is to read a single byte from the input stream and return it as an integer. It does this by calling the read method with a byte array of size 1, and then returning the first element of that array as an integer. If the result of the read operation is -1 (indicating the end of the input stream), then -1 is returned.

private boolean readHeader() throws IOException {
    int len = 0;
    while (len < 2) {
        int result = in.read(buffer, len, 2 - len);
        if (result < 0) {
            return false;
        }
        len += result;
    }
    int headerSize = WebsocketFrameHeader.size(buffer, 0);
    if (headerSize > 2) {
        while (len < headerSize) {
            int result = in.read(buffer, len, headerSize - len);
            if (result < 0) {
                return false;
            }
            len += result;
        }
    }
    header.write(buffer, 0, headerSize);
    return true;
}

The readHeader method is defined in the WebsocketInputStream class and is responsible for reading the header of a WebSocket frame. Here is a step-by-step description of its functionality:

1. Create a variable len and set it to 0.
2. Start a while loop and continue until len is less than 2.
3. Read from the input stream (in) and store the result in a variable result using the read method of the input stream. The buffer is used as the destination for the read bytes. The number of bytes to read is 2 - len, which ensures that two bytes are read in total.
4. Check if result is less than 0. If true, it means that the end of the stream has been reached, so return false.
5. Increment len by the value of result to keep track of the number of bytes read so far.
6. If the code execution reaches this point, it means that len is at least 2.
7. Calculate the size of the header by calling the size method of the WebsocketFrameHeader class, passing in the buffer and 0 as parameters. Store the result in a variable headerSize.
8. Check if headerSize is greater than 2. If true, it means that the header contains metadata beyond the initial two bytes.
9. Start a while loop and continue until len is less than headerSize.
10. Read from the input stream (in) and store the result in a variable result using the read method of the input stream. The number of bytes to read is headerSize - len, which ensures that the remaining bytes of the header are read.
11. Check if result is less than 0. If true, it means that the end of the stream has been reached, so return false.
12. Increment len by the value of result to keep track of the number of bytes read so far.
13. If the code execution reaches this point, it means that all the bytes of the header have been read.
14. Write the header bytes to the header object using the write method, passing in the buffer, 0, and headerSize as parameters.
15. Return true to indicate that the header has been successfully read.

The readHeader method in the io.nats.client.support.WebsocketInputStream class is responsible for reading the header of a WebSocket frame from an input stream.

The method initially reads 2 bytes from the input stream and stores them in a buffer. If the result is less than 0 (signifying the end of the input stream), the method returns false. Otherwise, it keeps reading from the input stream until it has read 2 bytes.

The method then calculates the header size using the WebsocketFrameHeader.size method, passing the buffer and the offset 0. If the header size is greater than 2, the method continues reading from the input stream until it has read headerSize bytes.

Finally, the method writes the header bytes from the buffer to the header object and returns true.

Overall, the readHeader method is responsible for reading and processing the header of a WebSocket frame from an input stream.

Token

The Token class represents a token, which is an essential element for parsing and processing data. This class provides a structure to store and manage tokens, allowing engineers to easily manipulate and analyze data using tokens.

JsonParser

The JsonParser class is a public class that provides functionality for parsing JSON data. It allows developers to easily convert JSON strings or files into Java objects, making it easier to work with JSON data in a structured and organized manner. The class offers various methods for parsing JSON, including parsing from a string, parsing from a file, and parsing directly from an input stream. Additionally, it supports parsing of JSON arrays, objects, and individual values, supporting a wide range of JSON data structures.

public static JsonValue parseUnchecked(char[] json) {
    try {
        return parse(json);
    } catch (JsonParseException j) {
        throw new RuntimeException(j);
    }
}

This method is a public static method that takes a single parameter json of type char[] and returns a JsonValue.

1. The method starts by wrapping the core parsing logic in a try-catch block.

2. Inside the try block, the parse(json) method is called to parse the given JSON string.

3. If the JSON parsing is successful, the parsed JsonValue object is returned.

4. If an exception of type JsonParseException is caught during the parsing process, it is wrapped in a RuntimeException and rethrown.

5. Upon catching the JsonParseException, a new instance of RuntimeException is created with the caught exception as the cause.

6. The RuntimeException is then thrown, propagating the original exception as an unchecked exception.

Note: This method provides a convenient way to parse JSON strings without explicitly handling the checked JsonParseException, allowing for cleaner code at the calling code level. However, it also introduces a risk of catching other types of exceptions and throwing them as unchecked exceptions. Hence, caution should be exercised while using this method.

The parseUnchecked method in the JsonParser class is a static method that takes a char array containing JSON data as input and returns a JsonValue object.

Internally, the method calls another method parse to parse the JSON data. If there is a JsonParseException during the parsing process, the method catches it and throws a RuntimeException with the same exception as the cause.

This method is useful when you want to parse JSON data without explicitly handling the exception. However, be aware that this method may throw a RuntimeException if the parsing fails.

public static JsonValue parseUnchecked(char[] json, int startIndex) {
    try {
        return parse(json, startIndex);
    } catch (JsonParseException j) {
        throw new RuntimeException(j);
    }
}

This method is used to parse a JSON string into a Java JsonValue object. It takes a character array representing the JSON string and the starting index as parameters. If the JSON parsing fails and throws a JsonParseException, it catches the exception and rethrows a RuntimeException.

public static JsonValue parseUnchecked(char[] json, int startIndex)

• json : a character array representing the JSON string to be parsed.
• startIndex : the starting index in the json array from where parsing should begin.

JsonValue : a Java object representing the parsed JSON value.

1. Invoke the parse method with the json and startIndex parameters.
2. If the parsing is successful, return the parsed JsonValue.
3. If a JsonParseException is thrown during the parsing process: a. Catch the exception. b. Throw a RuntimeException with the caught JsonParseException as its cause.

The parseUnchecked method, defined in the JsonParser class in the io.nats.client.support package, is responsible for parsing a JSON string into a JsonValue object without explicitly handling any exceptions.

The method takes a char array json and an int startIndex as parameters. It internally calls the parse method from the same class, passing the json and startIndex values. If the parse method throws a JsonParseException, it catches the exception and rethrows it as a RuntimeException.

In other words, the parseUnchecked method provides a simplified way to parse a JSON string without having to handle the JsonParseException explicitly. However, it does come with the risk of an unchecked exception being thrown if the given JSON string is invalid.

public static JsonValue parseUnchecked(char[] json, Option... options) {
    try {
        return parse(json, options);
    } catch (JsonParseException j) {
        throw new RuntimeException(j);
    }
}

The parseUnchecked method in the io.nats.client.support.JsonParser class is responsible for parsing a JSON string and returning a JsonValue object. Below is a step-by-step description of what this method does:

1. The parseUnchecked method accepts two parameters: json, a character array containing the JSON string to be parsed, and options, an optional array of Option objects.
2. The method tries to parse the JSON string using the parse method, passing in the json and options parameters.
3. If the parse is successful, the method returns the resulting JsonValue object.
4. If an exception of type JsonParseException is thrown during the parse, the method catches it and rethrows it as a RuntimeException. This is done to simplify error handling, as the parse method may throw a checked exception.
5. If the exception is rethrown as a RuntimeException, the caller of the parseUnchecked method will need to handle it appropriately.

Overall, the parseUnchecked method provides a simplified way to parse a JSON string without having to handle checked exceptions directly.

The parseUnchecked method is a static method defined in the JsonParser class within the io.nats.client.support package.

This method takes a char array json as input, along with optional Option arguments. The purpose of this method is to parse the given JSON string and return a JsonValue object.

Internally, the method calls the parse method from the same class which returns a JsonValue object. If a JsonParseException occurs during the parsing process, it is caught and re-thrown as a RuntimeException.

Overall, the parseUnchecked method allows for easy and unchecked parsing of a JSON string into a JsonValue object, simplifying exception handling for the caller.

public static JsonValue parseUnchecked(char[] json, int startIndex, Option... options) {
    try {
        return parse(json, startIndex, options);
    } catch (JsonParseException j) {
        throw new RuntimeException(j);
    }
}

The parseUnchecked method is defined in the io.nats.client.support.JsonParser class.

The parseUnchecked method is used to parse a JSON value from a character array, starting from a specified index. This method internally calls the parse method and handles any JsonParseException by throwing a RuntimeException.

public static JsonValue parseUnchecked(char[] json, int startIndex, Option... options)

The method takes the following parameters:

1. json - A character array containing the JSON string to parse.
2. startIndex - An integer representing the index in the json array from where the parsing should start.
3. options (optional) - One or more Option objects specifying parsing options.

The method returns a JsonValue representing the parsed JSON value.

The method may throw a RuntimeException if a JsonParseException occurs during parsing.

char[] json = "{\"name\": \"John\", \"age\": 30}".toCharArray();
int startIndex = 0;

try {
    JsonValue result = JsonParser.parseUnchecked(json, startIndex);
    System.out.println(result);
} catch (RuntimeException e) {
    System.err.println("Failed to parse JSON: " + e.getMessage());
}

In the above example, the parseUnchecked method is called with a JSON string and a starting index of 0. The parsed JsonValue is then printed to the console. If a JsonParseException occurs, a RuntimeException is thrown and the error message is printed to the console.

The parseUnchecked method in the JsonParser class is a public static method that allows you to parse a JSON string into a JsonValue object.

This method takes in three parameters:

• json: a character array representing the JSON string to be parsed
• startIndex: an integer representing the starting index of the JSON string
• options: an optional array of Option objects that can be used to customize the parsing behavior

Internally, the parseUnchecked method calls the parse method from the same class, passing in the provided parameters and options. If an exception of type JsonParseException is caught during the parsing process, it is wrapped in a RuntimeException and re-thrown.

Overall, the purpose of this method is to provide a convenient way to parse a JSON string into a JsonValue object, while handling any parsing exceptions in a consistent manner.

public static JsonValue parseUnchecked(String json) {
    try {
        return parse(json);
    } catch (JsonParseException j) {
        throw new RuntimeException(j);
    }
}

The parseUnchecked method in the JsonParser class is used to parse JSON data provided as a string and return a corresponding JsonValue object.

1. The method accepts a json parameter, which is a string containing the JSON data to be parsed.
2. Inside the method, a try-catch block is used to handle any potential JsonParseException that may occur during parsing.
3. The parse method is called with the json parameter to parse the JSON data and return a JsonValue object.
4. If no exception occurs during parsing, the parsed JsonValue object is returned.
5. If a JsonParseException occurs, it is caught in the catch block.
6. Inside the catch block, a RuntimeException is thrown with the caught JsonParseException as the cause.
7. This allows any exception during parsing to be re-thrown as a RuntimeException.
8. Finally, the parseUnchecked method is concluded.

Note: It's important to handle exceptions during parsing JSON data as parsing errors can occur if the JSON structure is not properly formatted.

The parseUnchecked method in the JsonParser class is a static method that takes a JSON string as input and returns a JsonValue object.

This method calls the parse method, which is responsible for parsing the JSON string and returning the corresponding JsonValue object. However, if a JsonParseException occurs during the parsing process, the method catches the exception and rethrows it as a RuntimeException to ensure the caller is aware of the failure.

The parseUnchecked method is designed to provide a convenient way to parse a JSON string without explicitly handling the JsonParseException. This is useful in scenarios where the caller expects the input JSON to be valid and does not want to handle the exception explicitly.

public static JsonValue parseUnchecked(String json, int startIndex) {
    try {
        return parse(json, startIndex);
    } catch (JsonParseException j) {
        throw new RuntimeException(j);
    }
}

parseUnchecked Method Description

The parseUnchecked method in class io.nats.client.support.JsonParser is used to parse a JSON string starting from a specified index. It takes two parameters, a String representing the JSON string to be parsed, and an int representing the index at which parsing should begin.

1. The method starts by wrapping the parsing logic in a try-catch block. This is done to catch any JsonParseException that may occur while parsing the JSON string.

2. Inside the try block, the parse method is called, passing the json string and startIndex as arguments. The parse method is responsible for parsing the JSON string and returning the parsed result as a JsonValue object.

3. If the parsing is successful, the parsed JsonValue object is returned from the parseUnchecked method.

4. However, if a JsonParseException is caught during parsing, the method throws a RuntimeException. This is done by wrapping the caught exception in a RuntimeException and rethrowing it. This allows the calling code to handle the exception in a consistent manner.