Hi Fredrik,
On 15/03/2025 21:15, Fredrik Roubert wrote:
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.
No, according to RFC 4517:
line-char = %x00-23
/ (%x5C "24") ; escaped "$"
/ %x25-5B
/ (%x5C "5C") ; escaped "\"
/ %x5D-7F
/ UTFMB
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 […]".
Yes, I probably dismissed your concern, and now I get a better
understanding on where you came from.
[…], 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.
My words is always to be questionned ;-)
Actually, putting the PostAddress class in utils would be better, I
think. You are plain right in that it makes no sense to have those two
classes (GT and PA) in two different packages, and we have made a
mistake in putting GT in utils, but it's too late to fix it (it's an
API, changing it would break the contract with users).
So I suggest you do the way you proposed in your first mail: put the PA
class in utils beside GT (but dont call it PostalAddressSyntax, just
PostalAddress).
Sorry for this useless thread, it could have been shorter, but I guess I
had to think out loud to get to realize IO was wrong...
Thanks!
Cheers // Fredrik Roubert
