001/*
002 * Copyright 2015-2022 Transmogrify LLC, 2022-2025 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.pyranid;
018
019import javax.annotation.Nonnull;
020import javax.annotation.concurrent.ThreadSafe;
021import java.util.Optional;
022
023/**
024 * Encapsulates {@link java.sql.PreparedStatement} parameter data meant to be bound to a DBMS-specific type (for example, {@code JSON} or {@code JSONB} for PostgreSQL) by {@link PreparedStatementBinder}.
025 * <p>
026 * Stardard instances may be constructed via {@link Parameters#json(String)} and {@link Parameters#json(String, BindingPreference)}.
027 * <p>
028 * Implementations should be threadsafe.
029 *
030 * @author <a href="https://www.revetkn.com">Mark Allen</a>
031 * @since 3.0.0
032 */
033@ThreadSafe
034public interface JsonParameter {
035        /**
036         * Specifies how a {@link JsonParameter} should be bound: binary (for example, {@code JSONB} for PostgreSQL), or text.
037         *
038         * @author <a href="https://www.revetkn.com">Mark Allen</a>
039         * @since 3.0.0
040         */
041        enum BindingPreference {
042                /**
043                 * Prefer a binary/native JSON type when available (for example, {@code JSONB} for PostgreSQL), otherwise falls back to {@link #TEXT}.
044                 */
045                BINARY,
046                /**
047                 * Prefer to bind as text (for example, {@code VARCHAR}/{@code TEXT}/{@code NVARCHAR} or {@code JSON} for PostgreSQL).
048                 */
049                TEXT
050        }
051
052        /**
053         * Gets the "stringified" JSON.
054         *
055         * @return the "stringified" JSON
056         */
057        @Nonnull
058        Optional<String> getJson();
059
060        /**
061         * Gets how the JSON should be bound (automatic, binary, text).
062         *
063         * @return how the JSON should be bound
064         */
065        @Nonnull
066        BindingPreference getBindingPreference();
067}