Skip to content

chore(docs): update javadoc for Profile interface #103

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jorsol merged 1 commit into from
May 11, 2026
Merged

chore(docs): update javadoc for Profile interface #103

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 38 additions & 21 deletions stringprep/src/main/java/com/ongres/stringprep/Profile.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@
* processing options.
*
* <p>Stringprep profiles can also exclude characters that should not normally appear in text that
* is used in the protocol. The profile can prevent such characters by changing the characters to be
* excluded to other characters, by removing those characters, or by causing an error if the
* is used in the protocol. The profile can prevent such characters by mapping the prohibited
* characters to replacement characters, by removing those characters, or by causing an error if the
* characters would appear in the output.
*
* @since 2.0
Expand All @@ -32,11 +32,11 @@ public interface Profile {
* as user-entered names for digital certificate authorities and DNS lookups.
*
* @implNote The default method sets the storedStrings Stringprep parameter to {@code false}, as
* "queries" MAY include unassigned code points. This method should not necessarily be
* overridden by implementations.
* "queries" MAY include unassigned code points. Overriding this method is
* generally unnecessary unless specific String-based optimizations are required.
*
* @param string to prepare based on a "stringprep" profile.
* @return The prepared String.
* @return The prepared string.
* @throws IllegalArgumentException if there is a prohibited output.
* @since 2.1
*/
Expand All @@ -49,11 +49,19 @@ default char[] prepareQuery(char[] string) {
* as user-entered names for digital certificate authorities and DNS lookups.
*
* @implNote The default method sets the storedStrings Stringprep parameter to {@code false}, as
* "queries" MAY include unassigned code points. This method should not necessarily be
* overridden by implementations.
* "queries" MAY include unassigned code points. Overriding this method is generally
* unnecessary unless specific String-based optimizations are required.
* @apiNote This is a convenience method that delegates to {@link #prepareQuery(char[])}.
* <p>
* <strong>Security Warning:</strong> This method is <em>not</em> recommended for
* handling sensitive data like passwords or private keys. Because {@link String}
* objects are immutable, their contents cannot be zeroed out after use and may persist in
* memory indefinitely. For cryptographic secrets, use
* {@link #prepareQuery(char[])} to ensure the data can be cleared immediately after
* processing.
*
* @param string to prepare based on a "stringprep" profile.
* @return The prepared String.
* @return The prepared string.
* @throws IllegalArgumentException if there is a prohibited output.
*/
default String prepareQuery(String string) {
Expand All @@ -65,11 +73,11 @@ default String prepareQuery(String string) {
* names in digital certificates and DNS domain name parts.
*
* @implNote The default method sets the storedStrings Stringprep parameter to {@code true}, as
* "stored strings" MUST NOT contain unassigned code points. This method should not
* necessarily be overridden by implementations.
* "stored strings" MUST NOT contain unassigned code points. Overriding this method is
* generally unnecessary unless specific String-based optimizations are required.
*
* @param string to prepare based on a "stringprep" profile.
* @return The prepared String.
* @return The prepared string.
* @throws IllegalArgumentException if there is a prohibited output.
* @since 2.1
*/
Expand All @@ -82,11 +90,19 @@ default char[] prepareStored(char[] string) {
* names in digital certificates and DNS domain name parts.
*
* @implNote The default method sets the storedStrings Stringprep parameter to {@code true}, as
* "stored strings" MUST NOT contain unassigned code points. This method should not
* necessarily be overridden by implementations.
* "stored strings" MUST NOT contain unassigned code points. Overriding this method is
* generally unnecessary unless specific String-based optimizations are required.
* @apiNote This is a convenience method that delegates to {@link #prepareStored(char[])}.
* <p>
* <strong>Security Warning:</strong> This method is <em>not</em> recommended for
* handling sensitive data like passwords or private keys. Because {@link String}
* objects are immutable, their contents cannot be zeroed out after use and may persist in
* memory indefinitely. For cryptographic secrets, use
* {@link #prepareStored(char[])} to ensure the data can be cleared immediately after
* processing.
*
* @param string to prepare based on a "stringprep" profile.
* @return The prepared String.
* @return The prepared string.
* @throws IllegalArgumentException if there is a prohibited output.
*/
default String prepareStored(String string) {
Expand All @@ -97,16 +113,17 @@ default String prepareStored(String string) {
* Any additional mapping tables specific to the profile.
*
* @implSpec Profiles that requires additional mapping tables must implement this method. A code
* point match return the mapped array with the new code points or if there is no match,
* point match returns the mapped array with the new code points or if there is no match,
* it should return the same input code point as {@code new int[] {codePoint};}.
* Implementations MUST also set {@link Option#ADDITIONAL_MAPPING} to enable the
* proccesing of this rule.
* processing of this rule.
*
* @implNote The default implementation always return the same code point mapping ({@code new
* int[] {codePoint}}), no change is done to the code point.
*
* @param codePoint the character (Unicode code point) to be mapped.
* @return Mapping with the int[] array or with the same codePoint.
* @return An array containing the mapped code points, or an array containing the original
* code point if no mapping applies.
*/
default int[] additionalMappingTable(int codePoint) {
return new int[] {codePoint};
Expand All @@ -116,11 +133,11 @@ default int[] additionalMappingTable(int codePoint) {
* Any additional characters that are prohibited as output specific to the profile.
*
* @implSpec Profiles that prohibit additional characters must implement this method. A code point
* match return {@code true}, or if the code point should not be prohibited it should
* return {@code false}. Implementations MUST also set
* {@link Option#FORBID_ADDITIONAL_CHARACTERS} to enable the proccesing of this rule.
* match returns {@code true}, or if the code point should not be prohibited it returns
* {@code false}. Implementations MUST also set
* {@link Option#FORBID_ADDITIONAL_CHARACTERS} to enable the processing of this rule.
*
* @implNote The default implementation always return {@code false}, all characters are accepted.
* @implNote The default implementation always returns {@code false}; all characters are accepted.
*
* @param codePoint the character (Unicode code point) to be tested.
* @return {@code true} if the given {@code codePoint} is prohibited on this profile.
Expand Down
Loading