DOCSP-18711: Explain BsonRepresentation limitation

[norareidy]

Pull Request Info

PR Reviewing Guidelines

JIRA - https://jira.mongodb.org/browse/DOCSP-18711
Staging - https://preview-mongodbnorareidy.gatsbyjs.io/java/DOCSP-18711-bson-representation/fundamentals/data-formats/pojo-customization/#bsonrepresentation-error-example

Self-Review Checklist

• Is this free of any warnings or errors in the RST?
• Did you run a spell-check?
• Did you run a grammar-check?
• Are all the links working?
• Are the facets and meta keywords accurate?

[jordan-smith721]

LGTM w/ two small things!

[jordan-smith721]

Suggestoin for clarity:

Suggested change

	``Product`` POJO. This example attempts to represent ``Long`` values as ``DateTime``
	``Product`` POJO. This example attempts to use ``@BsonRepresentation`` to represent ``Long`` values as ``DateTime``

[jordan-smith721]

Suggested change

	Then, you can add an instance of the ``LongCodec`` to your ``CodecRegistry``, which contains
	Then, add an instance of the ``LongCodec`` to your ``CodecRegistry``, which contains

[norareidy]

Note to tech reviewer: I'm a little uncertain about this example code. The example provided in the ticket didn't convert between Long and Datetime, so I wrote my own example. Let me know if this needs to be updated!

[rozza]

This would convert all Longs to a Date times, which wouldn't be desired by users.

@BsonRepresentation(BsonType.DATE_TIME)
private Long purchaseDate;

Requires a Codec that implements RepresentationConfigurable<Long>. eg:

public class LongRepresentableCodec implements Codec<Long>, RepresentationConfigurable<Long> {
    private final BsonType representation;

    /**
     * Constructs a LongRepresentableCodec with a Int64 representation.
     */
    public LongRepresentableCodec() {
        representation = BsonType.INT64;
    }

    private LongRepresentableCodec(final BsonType representation) {
        this.representation = representation;
    }

    @Override
    public BsonType getRepresentation() {
        return representation;
    }

    @Override
    public Codec<Long> withRepresentation(final BsonType representation) {
        if (representation != BsonType.INT64 && representation != BsonType.DATE_TIME) {
            throw new CodecConfigurationException(representation + " is not a supported representation for LongRepresentableCodec");
        }
        return new LongRepresentableCodec(representation);
    }


    @Override
    public void encode(final BsonWriter writer, final Long value, final EncoderContext encoderContext) {
        switch (representation) {
            case INT64:
                writer.writeInt64(value);
                break;
            case DATE_TIME:
                writer.writeDateTime(value);
                break;
            default:
                throw new BsonInvalidOperationException("Cannot encode a Long to a " + representation);
        }
    }

    @Override
    public Long decode(final BsonReader reader, final DecoderContext decoderContext) {
        switch (representation) {
            case INT64:
                return reader.readInt64();
            case DATE_TIME:
                return reader.readDateTime();
            default:
                throw new CodecConfigurationException("Cannot decode " + representation + " to a Long");
        }
    }

    @Override
    public Class<Long> getEncoderClass() {
        return Long.class;
    }
}

[norareidy]

Great, thanks for providing this code!

[rozza]

Provided a Codec<Long> that implements RepresentationConfigurable<Long> so that users can use it to either encode / decode long values or date times.