On Fri 14 Mar 2025 at 00:27 +0100, Emmanuel Lécharny wrote:
> What I mean is that the API can't know if a '$' or a '\' are to be escaped
> (there is no third char to be escaped, btw),
You forgot the newline character, that's the third one.
> OTOH, if you suggest we should let an API user provides a multi-line String
> and let the API do the escaping work, instead of doing it in Studio, I'm not
> against it, I wasn't thinking it would have been useful when we first wrote
> the API, but thinking about it now, I can see what you mean.
Yes, exactly, that's what all this is about. As I wrote in my initial
mail on 23 February: "It's not a particularly complicated syntax to
decode or encode, just a few characters that need to be unescaped or
escaped, but it doesn't seem reasonable to me that everyone who needs to
work with Postal Address entries should have to write their own
implementations of this […]".
> […], it would be a better idea to store them into o.a.d.api.ldap.model.type
> (a new package) that would store the Classes for values we may want to
> encode/decode.
OK, then the updated proposal now looks like this:
package org.apache.directory.api.ldap.model.type;
/**
* Create unescapers and escapers for the RFC 4517 Postal Address syntax.
*
* <pre>
* PostalAddress = line *( DOLLAR line )
* line = 1*line-char
* line-char = %x00-23
* / (%x5C "24") ; escaped "$"
* / %x25-5B
* / (%x5C "5C") ; escaped "\"
* / %x5D-7F
* / UTFMB
* </pre>
*/
public final class PostalAddressSyntax
{
/**
* Create an unescaper that uses the specified line separator.
*
* @param separator the separator to output between address lines
* @return a commons-text translator object for unescaping
*/
public static CharSequenceTranslator createUnescaper( String separator );
/**
* Create an escaper that uses the specified line separator.
*
* @param separator the separator used between address lines
* @return a commons-text translator object for escaping
*/
public static CharSequenceTranslator createEscaper( String separator );
}
And some example code for how a user of this library would use all this:
import java.util.Date;
import org.apache.commons.text.translate.CharSequenceTranslator;
import org.apache.directory.api.ldap.model.entry.Value;
import org.apache.directory.api.ldap.model.type.PostalAddressSyntax;
import org.apache.directory.api.util.GeneralizedTime;
// Integer syntax
Value value = entry.get("uidNumber").get();
int number = Integer.parseInt(value.toString());
// Generalized Time syntax
Value value = entry.get("modifyTimestamp").get();
Date timestamp = GeneralizedTime.getDate(value.toString());
// Postal Address syntax
CharSequenceTranslator unescaper = PostalAddressSyntax.createUnescaper("\n");
Value value = entry.get("homePostalAddress").get();
String address = unescaper.translate(value.toString());
I find it a bit unintuitive that the functions for Generalized Time syntax
and Postal Address syntax are in totally different packages, but I take
your word for it that this fits better with the overall design.
Cheers // Fredrik Roubert
--
Forsterstrasse 64 | +41 78 8170377
CH-8044 Zürich | https://roubert.name/fredrik/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@directory.apache.org
For additional commands, e-mail: dev-h...@directory.apache.org
