Модуль pljava позволяет писать хранимые процедуры, триггеры и функции на языке Java и выполнять их обслуживающим процессом Postgres Pro.

pljava предоставляет следующие основные возможности:

Серверные функции и триггеры пишутся на языке Java с помощью подключённой напрямую эффективной версии стандартного JDBC API, который прозрачно поддерживается pljava, а также с помощью расширенных возможностей, которые есть в pljava API.

Функция или триггер в SQL-коде сопоставляется со статическим методом в Java-классе. Для выполнения функции соответствующий класс должен быть установлен в базе данных. pljava предоставляет набор функций, которые помогают устанавливать и поддерживать Java-классы.

Компилятор Java также создаёт дескриптор развёртывания SQLJ, содержащий SQL-операторы, которые должны быть выполнены при установке и удалении скомпилированного Java-кода обслуживающим процессом Postgres Pro.

Скомпилированный Java-код и файл дескриптора развёртывания хранятся вместе в архиве Java (JAR-файл). Функция sqlj.install_jar загружает код в обслуживающий процесс Postgres Pro и выполняет необходимые SQL-команды из дескриптора развёртывания, делая новые типы, функции и триггеры доступными для использования.

pljava реализует стандартизированный способ передачи параметров и возвращаемых значений. Сложные типы и множества передаются с помощью стандартного класса ResultSet драйвера JDBC. Большое внимание было уделено тому, чтобы не вводить никакие собственные интерфейсы, за исключением случаев крайней необходимости, чтобы Java-код, написанный с помощью pljava, был максимально независимым от баз данных.

Драйвер JDBC включён в pljava. Этот драйвер написан непосредственно поверх внутренних SPI-функций Postgres Pro. Этот драйвер очень важен, поскольку функции и триггеры очень часто повторно используют базу данных. В этих случаях они должны использовать те же границы транзакций, которые использовались вызывающим кодом.

Модуль pljava оптимизирован для повышения производительности. Виртуальная машина Java выполняется в рамках того же обслуживающего процесса. Это гарантирует очень низкие накладные расходы на вызовы. Модуль pljava разработан с целью использовать весь потенциал Java непосредственно в самой базе данных, чтобы бизнес-логика, интенсивно использующая базы данных, могла выполняться максимально близко к фактическим данным.

Стандартный интерфейс Java Native Interface (JNI) используется при передаче вызовов из обслуживающего процесса в виртуальную машину Java и обратно.

Модуль pljava поставляется вместе с Postgres Pro Enterprise в виде отдельного пакета pljava-ent-16 (подробная инструкция по установке приведена в Главе 17).

Функции sqlj.install_jar, sqlj.replace_jar и sqlj.remove_jar могут затрагивать дескриптор развёртывания, позволяя SQL-командам выполняться после установки JAR-файла или перед его удалением.

Дескриптор добавляется в JAR-файл как обычный текстовый файл. В манифесте JAR-файла должна быть запись, указывающая на то, что этот файл является дескриптором развёртывания SQLJ.

Name: deployment/examples.ddr
SQLJDeploymentDescriptor: TRUE

Такой файл может быть написан вручную в соответствии с форматом ниже, но обычно в исходный код добавляются определённые аннотации Java, как описано в разделе Автоматическая генерация SQL-кода. Затем компилятор генерирует файл дескриптора развёртывания во время компиляции исходного Java-кода. Скомпилированные классы и файл .ddr могут быть вместе помещены в JAR-файл.

Формат дескриптора развёртывания устанавливается стандартом ISO/IEC 9075-13:2003.

<файл_дескриптора> ::=
  SQLActions <левая_скобка> <правая_скобка> <знак_равенства>
  { [ <двойные_кавычки> <группа_действий> <двойные_кавычки>
    [ <запятая> <двойные_кавычки> <группа_действий> <двойные_кавычки> ] ] }

<группа_действий> ::=
    <действия_установки>
  | <действия_удаления>

<действия_установки> ::=
  BEGIN INSTALL [ <команда> <точка_с_запятой> ]... END INSTALL

<действия_удаления> ::=
  BEGIN REMOVE [ <команда> <точка_с_запятой> ]... END REMOVE

<команда> ::=
    <выражение_SQL>
  | <блок_исполнителей>

<выражение_SQL> ::= <компонент_SQL>...

<блок_исполнителей> ::=
  BEGIN <имя_исполнителя> <компонент_SQL>... END <имя_исполнителя>

<имя_исполнителя> ::= <идентификатор>

<компонент_SQL> ::= ! лексическая единица SQL, указанная под термином
                "<token>" в подпункте 5.2 в стандарте ISO/IEC 9075-2.

Если используются блоки исполнителей, pljava по умолчанию рассматривает только те, у которых имя исполнителя PostgreSQL (без учёта регистра). Пример дескриптора развёртывания:

SQLActions[] = {
  "BEGIN INSTALL
    CREATE FUNCTION javatest.java_getTimestamp()
      RETURNS timestamp
      AS 'org.postgresql.pljava.example.Parameters.getTimestamp'
      LANGUAGE java;
  END INSTALL",
  "BEGIN REMOVE
    DROP FUNCTION javatest.java_getTimestamp();
  END REMOVE"
}

Хотя по умолчанию распознается только имя исполнителя PostgreSQL, можно указать имена исполнителей, подлежащих распознаванию, в виде списка в параметре конфигурации pljava.implementors. Этот список проверяется после каждой команды при выполнении дескриптора развёртывания. Это позволяет коду в дескрипторе приобретать элементарную форму условного управления выполнением, которая достигается путём изменения блока исполнителей для выполнения на основе обнаруженных условий.

Сигнатура метода триггера предопределена. Метод триггера всегда должен возвращать тип void и иметь параметр, реализующий интерфейс org.postgresql.pljava.TriggerData. Интерфейс TriggerData предоставляет доступ к двум экземплярам java.sql.ResultSet: один экземпляр представляет старую строку, а другой — новую. Старая строка доступна только для чтения, а новая строка может быть обновлена.

Экземпляры ResultSet доступны только для триггеров, которые срабатывают для каждой строки. Триггеры удаления не имеют новой строки, а триггеры вставки не имеют старой строки. Только у триггеров обновления есть обе строки.

В дополнение к этим экземплярам существуют несколько логических методов, позволяющих получить более подробную информацию о триггере.

CREATE TABLE mdt (
    id int4,
    idesc text,
    moddate timestamp DEFAULT CURRENT_TIMESTAMP NOT NULL);

CREATE FUNCTION moddatetime()
    RETURNS trigger
    AS 'org.postgresql.pljava.example.Triggers.moddatetime'
    LANGUAGE java;

CREATE TRIGGER mdt_moddatetime
    BEFORE UPDATE ON mdt
    FOR EACH ROW
    EXECUTE PROCEDURE moddatetime (moddate);

Соответствующий Java-код выглядит следующим образом:

/**
* Обновить время изменения при обновлении строки
*/
static void moddatetime(TriggerData td)
throws SQLException
{
    if(td.isFiredForStatement())
    throw new TriggerException(td, "can't process STATEMENT events");

    if(td.isFiredAfter())
    throw new TriggerException(td, "must be fired before event");

    if(!td.isFiredByUpdate())
    throw new TriggerException(td, "can only process UPDATE events");

    ResultSet _new = td.getNew();
    String[] args = td.getArguments();
    if(args.length != 1)
    throw new TriggerException(td, "one argument was expected");

    _new.updateTimestamp(args[0], new Timestamp(System.currentTimeMillis()));
}

С помощью pljava можно установить сопоставление между произвольным типом и Java-классом. Для этого необходимо выполнить следующие предварительные требования:

package org.postgresql.pljava.example;

import java.sql.SQLData;
import java.sql.SQLException;
import java.sql.SQLInput;
import java.sql.SQLOutput;

public class Point implements SQLData {
    private double m_x;
    private double m_y;
    private String m_typeName;

    public String getSQLTypeName() {
    return m_typeName;
    }

    public void readSQL(SQLInput stream, String typeName) throws SQLException {
    m_x = stream.readDouble();
    m_y = stream.readDouble();
    m_typeName = typeName;
    }

    public void writeSQL(SQLOutput stream) throws SQLException {
    stream.writeDouble(m_x);
    stream.writeDouble(m_y);
    }

    /* Значимый код, который действительно что-то делает с этим типом,
    * был намеренно опущен
    */
}

SELECT sqlj.add_type_mapping('point', 'org.postgresql.pljava.example.Point');

CREATE TYPE javatest.complextuple AS (x float8, y float8);

SELECT sqlj.add_type_mapping('javatest.complextuple',
        'org.postgresql.pljava.example.ComplexTuple');

package org.postgresql.pljava.example;

import java.sql.SQLData;
import java.sql.SQLException;
import java.sql.SQLInput;
import java.sql.SQLOutput;

public class ComplexTuple implements SQLData {
    private double m_x;
    private double m_y;
    private String m_typeName;

    public String getSQLTypeName()
    {
    return m_typeName;
    }

    public void readSQL(SQLInput stream, String typeName) throws SQLException
    {
    m_typeName = typeName;
    m_x = stream.readDouble();
    m_y = stream.readDouble();
    }

    public void writeSQL(SQLOutput stream) throws SQLException
    {
    stream.writeDouble(m_x);
    stream.writeDouble(m_y);
    }

    /* Значимый код, который действительно что-то делает с этим типом,
    * был намеренно опущен
    */
}

@MappedUDT(schema="javatest", name="complextuple",
structure={"x float8", "y float8"})
public class ComplexTuple implements SQLData {
...

В этом тексте предполагается, что уже есть представление о том, как создаются скалярные типы и как они добавляются в систему типов Postgres Pro. За подробной информацией обратитесь к разделу Пользовательские типы.

С точки зрения SQL создание нового скалярного типа с помощью Java-функций очень похоже на создание типа с помощью C-функций, но на самом деле отличается, если посмотреть на фактическую реализацию. Java требует, чтобы сопоставление между Java-классом и соответствующим SQL-типом выполнялось с помощью интерфейсов java.sql.SQLData, java.sql.SQLInput и java.sql.SQLOutput, используемых pljava. Кроме того, система типов Postgres Pro требует, чтобы каждый тип имел текстовое представление.

В примере ниже показано, как создать тип с именем javatest.complex. Имя соответствующего Java-класса будет org.postgresql.pljava.example.ComplexScalar.

Java-класс для скалярного пользовательского типа должен реализовывать интерфейс java.sql.SQLData. Кроме того, он также должен реализовывать метод parse(), который создаёт и возвращает экземпляр этого класса, и метод toString(), который возвращает то, что может быть разобрано методом parse().

package org.postgresql.pljava.example;

import java.io.IOException;
import java.io.StreamTokenizer;
import java.io.StringReader;
import java.sql.SQLData;
import java.sql.SQLException;
import java.sql.SQLInput;
import java.sql.SQLOutput;
import java.util.logging.Logger;

import org.postgresql.pljava.annotation.Function;
import org.postgresql.pljava.annotation.SQLType;
import org.postgresql.pljava.annotation.BaseUDT;

import static org.postgresql.pljava.annotation.Function.Effects.IMMUTABLE;
import static
        org.postgresql.pljava.annotation.Function.OnNullInput.RETURNS_NULL;

@BaseUDT(schema="javatest", name="complex",
        internalLength=16, alignment=BaseUDT.Alignment.DOUBLE)
public class ComplexScalar implements SQLData
{
    private double m_x;
    private double m_y;
    private String m_typeName;

    @Function(effects=IMMUTABLE, onNullInput=RETURNS_NULL)
    public static ComplexScalar parse(String input, String typeName)
    throws SQLException
    {
    try
    {
        StreamTokenizer tz = new StreamTokenizer(new StringReader(input));
        if(tz.nextToken() == '('
        && tz.nextToken() == StreamTokenizer.TT_NUMBER)
        {
            double x = tz.nval;
            if(tz.nextToken() == ','
            && tz.nextToken() == StreamTokenizer.TT_NUMBER)
            {
                double y = tz.nval;
                if(tz.nextToken() == ')')
                {
                return new ComplexScalar(x, y, typeName);
                }
            }
        }
        throw new SQLException("Unable to parse complex from string \""
        + input + '"');
    }
    catch(IOException e)
    {
        throw new SQLException(e.getMessage());
    }
    }

    public ComplexScalar()
    {
    }

    public ComplexScalar(double x, double y, String typeName)
    {
    m_x = x;
    m_y = y;
    m_typeName = typeName;
    }

    @Override
    public String getSQLTypeName()
    {
    return m_typeName;
    }

    @Function(effects=IMMUTABLE, onNullInput=RETURNS_NULL)
    @Override
    public void readSQL(SQLInput stream, String typeName) throws SQLException
    {
    m_x = stream.readDouble();
    m_y = stream.readDouble();
    m_typeName = typeName;
    }

    @Function(effects=IMMUTABLE, onNullInput=RETURNS_NULL)
    @Override
    public void writeSQL(SQLOutput stream) throws SQLException
    {
    stream.writeDouble(m_x);
    stream.writeDouble(m_y);
    }

    @Function(effects=IMMUTABLE, onNullInput=RETURNS_NULL)
    @Override
    public String toString()
    {
    s_logger.info(m_typeName + " toString");
    StringBuffer sb = new StringBuffer();
    sb.append('(');
    sb.append(m_x);
    sb.append(',');
    sb.append(m_y);
    sb.append(')');
    return sb.toString();
    }

    /* Значимый код, который действительно что-то делает с этим типом,
    * был намеренно опущен
    */
}

Для самого класса указана аннотация @BaseUDT, задающая SQL-схему, имя, а также длину и выравнивание, необходимые для внутренней формы хранения.

Так как компилятор знает, что класс является BaseUDT, он ожидает наличие методов parse(), toString(), readSQL() и writeSQL() и будет генерировать корректный SQL-код, чтобы объявить их в виде функций для Postgres Pro. Аннотации @Function здесь используются только, чтобы объявить функцию как постоянную, и определить поведение при входном значении NULL, поскольку эти значения не используются по умолчанию при объявлении функции.

pljava обрабатывает возвращаемое значение сложного типа как параметр IN или OUT. Если объявлена функция, которая возвращает сложный тип, нужно использовать Java-метод с логическим возвращаемым значением и с последним параметром типа java.sql.ResultSet, добавленным после всех видимых параметров метода. Выходной параметр будет инициализирован экземпляром ResultSet, который содержит одну строку и может обновляться.

CREATE FUNCTION createComplexTest(int, int)
  RETURNS complexTest
  AS 'foo.fee.Fum.createComplexTest'
  IMMUTABLE LANGUAGE java;

Механизм сопоставления метода pljava теперь будет находить следующий метод в классе foo.fee.Fum:

public static boolean complexReturn(int base, int increment, ResultSet receiver)
throws SQLException
{
  receiver.updateInt(1, base);
  receiver.updateInt(2, base + increment);
  receiver.updateTimestamp(3, new Timestamp(System.currentTimeMillis()));
  return true;
}

Возвращаемое значение указывает, следует ли считать параметр receiver актуальным кортежем (true) или NULL (false).

Возвращать множества довольно сложно. Не нужно сначала строить всё множество, а затем возвращать его, поскольку большие множества требуют излишних ресурсов. Лучше создавать по одной строке за один раз. Именно этого и ожидает обслуживающий процесс Postgres Pro от функции, которая возвращает SETOF <type>. <type> может быть скалярным типом, например int, float или varchar, сложным типом или типом RECORD.

CREATE FUNCTION javatest.getNames()
  RETURNS SETOF varchar
  AS 'foo.fee.Bar.getNames'
  IMMUTABLE LANGUAGE java;

package foo.fee;
import java.util.Iterator;

import org.postgresql.pljava.annotation.Function;
import static org.postgresql.pljava.annotation.Function.Effects.IMMUTABLE;

public class Bar
{
    @Function(schema="javatest", effects=IMMUTABLE)
    public static Iterator<String> getNames()
    {
        ArrayList<String> names = new ArrayList<>();
        names.add("Lisa");
        names.add("Bob");
        names.add("Bill");
        names.add("Sally");
        return names.iterator();
    }
}

CREATE FUNCTION javatest.listComplexTests(int, int)
  RETURNS SETOF complexTest
  AS 'foo.fee.Fum.listComplexTest'
  IMMUTABLE LANGUAGE java;

public class Fum implements ResultSetProvider
{
  private final int m_base;
  private final int m_increment;
  public Fum(int base, int increment)
  {
    m_base = base;
    m_increment = increment;
  }
  public boolean assignRowValues(ResultSet receiver, int currentRow)
  throws SQLException
  {
    // Остановить при достижении 12 строк
    //
    if(currentRow >= 12)
      return false;
    receiver.updateInt(1, m_base);
    receiver.updateInt(2, m_base + m_increment * currentRow);
    receiver.updateTimestamp(3, new Timestamp(System.currentTimeMillis()));
    return true;
  }
  public void close()
  {
    // В этом примере ничего не требуется
  }
  @Function(effects=IMMUTABLE, schema="javatest", type="complexTest")
  public static ResultSetProvider listComplexTests(int base, int increment)
  throws SQLException
  {
    return new Fum(base, increment);
  }
}

CREATE FUNCTION javatest.listSupers()
  RETURNS SETOF pg_user
  AS 'org.postgresql.pljava.example.Users.listSupers'
  LANGUAGE java;

CREATE FUNCTION javatest.listNonSupers()
  RETURNS SETOF pg_user
  AS 'org.postgresql.pljava.example.Users.listNonSupers'
  LANGUAGE java;

public class Users implements ResultSetHandle
{
  private final String m_filter;
  private Statement m_statement;

  public Users(String filter)
  {
    m_filter = filter;
  }

  public ResultSet getResultSet()
  throws SQLException
  {
    m_statement = DriverManager.getConnection("jdbc:default:connection")
      .createStatement();
    return m_statement.executeQuery("SELECT * FROM pg_user WHERE " + m_filter);
  }

  public void close()
  throws SQLException
  {
    m_statement.close();
  }

  @Function(schema="javatest", type="pg_user")
  public static ResultSetHandle listSupers()
  {
    return new Users("usesuper = true");
  }

  @Function(schema="javatest", type="pg_user")
  public static ResultSetHandle listNonSupers()
  {
    return new Users("usesuper = false");
  }
}

pljava содержит драйвер JDBC, который сопоставляется с SPI-функциями Postgres Pro. Подключение, которое сопоставляется с текущей транзакцией, можно получить с помощью следующего оператора:

Connection conn = DriverManager.getConnection("jdbc:default:connection");

Теперь можно подготавливать и выполнять операторы, как и с любым другим подключением JDBC. Есть несколько ограничений:

В обслуживающем процессе Postgres Pro можно перехватывать и обрабатывать исключения точно так же, как и любое другое исключение. Серверная структура ErrorData представлена в виде свойства класса ServerException, унаследованного от java.sql.SQLException. Механизм try/catch в Java синхронизирован с механизмом в обслуживающем процессе.

pljava всегда будет перехватывать исключения, которые вы не перехватываете. Они вызовут ошибку Postgres Pro, и сообщение будет записано в журнал с помощью утилит протоколирования Postgres Pro. Также будет выводиться трассировка стека исключения, если для параметра конфигурации log_min_messages установлено значение DEBUG1 или ниже.

Для точек сохранения Postgres Pro можно использовать стандартные методы setSavepoint() и releaseSavepoint() интерфейса java.sql.Connection. Применяются следующие ограничения:

Здесь под «функцией» имеется в виду функция pljava, которая вызывается из SQL-кода. Ограничения не запрещают организовывать Java-код в несколько методов, но точка сохранения не может существовать после окончательного возврата из Java-кода в вызывающий SQL-код.

pljava использует стандартный класс java.util.logging.Logger. Поэтому можно написать код так:

Logger.getAnonymousLogger().info(
    "Time is " + new Date(System.currentTimeMillis()));

В настоящее время Logger жёстко привязан к обработчику, который сопоставляет уровень протоколирования, указанный в параметре конфигурации log_min_messages, с корректным уровнем Logger и выводит все сообщения с помощью серверной функции ereport().

Важно отметить, что методы Logger позволяют быстро отбросить любое сообщение, которое протоколируется на более детальном уровне, чем уровень, сопоставленный из параметра Postgres Pro во время первого использования pljava в текущем сеансе. Такие сообщения даже никогда не доходят до функции ereport(), даже если значение параметра Postgres Pro позже изменяется.

Таким образом, если ожидаемые сообщения из Java-кода не показываются, убедитесь, что параметры Postgres Pro настроены достаточным образом во время первого использования pljava в сеансе, чтобы Java-код не отбрасывал эти сообщения. После запуска pljava параметры могут изменяться по мере необходимости и будут обычным образом управлять тем, что функция ereport() делает с сообщениями, которые pljava доставляет в неё.

Уровень для отсечки в Java устанавливается на основе более точного значения из значений параметров log_min_messages и client_min_messages.

Следующее сопоставление применяется между уровнями Logger и уровнями Postgres Pro:

Несколько параметров конфигурации могут влиять на работу pljava, включая некоторые общие параметры Postgres Pro, а также собственные параметры pljava.