Платформа Eclipse
Правила применения API

Версия 0.15 - Последнее исправление: 30 мая 2001 года, 12:00

В этом разделе рассмотрены правила применения клиентов API платформы Eclipse (и другие компоненты).

Что такое API

Платформа Eclipse определяет элементы API, применяемые клиентами (независимыми производителями программного обеспечения, разрабатывающими модули). В свою очередь модули могут определять элементы API для собственных клиентов и т.д. Элементы API представляют собой внешний интерфейс: они содержат спецификацию их предназначения и способа применения. Для элементов API предоставляется поддержка: группа разработки платформы Eclipse устранит ошибки реализации в случае отклонений от указанного алгоритма работы. Поскольку обработка изменений API может быть связана с затруднениями, группа разработки платформы Eclipse попытается эффективно расширить элементы API в последующих выпусках.

Каким образом определить API

По своей природе элементы API предусматривают наличие документации и спецификации. Это отличает их от прочих элементов, описывающих внутреннюю реализацию без опубликованной документации или спецификации. Таким образом, если вам не удалось найти документацию по какому-либо элементу, с большой вероятностью можно утверждать, что он не связан с API.

Для более четкого разграничения исходный код платформы разделен на пакеты API и прочие пакеты. Все элементы API объявлены в соответствующих пакетах API.

Остальные элементы рассматриваются в качестве описания внутренней реализации, характерной для отдельных клиентов. Допустимый код клиента не должен содержать ссылок на имена элементов, не связанных с API (даже с помощью интеллектуальных API Java). В некоторых случаях недопустимые ссылки запрещаются правилами обработки имен языка Java. Учитывая следующее простое правило, вы можете полностью избежать подобных неполадок:

Общие правила

Спецификация элементов API создается на основе комментариев документации по Java, указанных в исходном коде Java этих элементов. В некоторых случаях документация предоставляется в виде контракта. Например, для метода это может быть контракт, заключенный двумя сторонами - стороной вызывающей метод и стороной реализующей его. Ниже приведено основное правило: Термин "должен", употребляемый в контрактах на использование API, означает, что ответственность за выполнение условий контракта возлагается на другую сторону. Невыполнение условий может привести к ошибкам программирования, последствия которых не указываются, либо их невозможно предсказать. Прочие очевидные правила:

Вызов общедоступных методов API

С точки зрения большинства клиентов API Eclipse представляет собой набор общедоступных методов, входящих в состав классов и интерфейсов API, которые клиент может вызывать по мере необходимости.

Создание экземпляров классов API платформы

Обратите внимание, что не все настроенные классы API доступны для создания экземпляров. Условия создания экземпляров классов API описаны в соответствующих контрактах. Кроме того, контракт может устанавливать ответственность за остаточную инициализацию (например, настройку конкретного свойства перед активизацией экземпляра), а также за связанный жизненный цикл (например, вызов метода dispose() для освобождения ресурсов операционной системы, занятых экземпляром). Классы, экземпляры которых должны создавать клиенты, в документации по Java указываются явным образом (например, с помощью фразы, аналогичной "Допускает создание экземпляра клиентом").

Производные классы API платформы

В качестве производных классов можно использовать только подмножества классов API. Условия объявления производных классов API описаны в соответствующих контрактах исходных классов API. Кроме того, эти контракты устанавливают ответственность, связанную с инициализацией и жизненным циклом производных классов. Классы, производные классы которых должны создавать клиенты, в документации по Java выделяются явным образом (например, с помощью фразы, аналогичной "Допускает создание производных классов клиентом").

Вызов защищенных методов API

Вызов наследованных защищенных и общедоступных методов из производных классов в общем случае разрешен. Однако, в отличие вызова общедоступных методов за пределами иерархии в данном случае особое внимание следует обратить на правильность вызова.

Переопределение методов API

Переопределение предусмотрено только для части общедоступных и защищенных методов API. Для каждого метода API предусмотрен контракт производных классов, в котором описаны условия его переопределения в производном классе. По умолчанию переопределение запрещено. Обратите особое внимание на контракт производных классов конкретного переопределяемого метода. Условия контракта не передаются автоматически в ходе переопределения метода.

Реализация интерфейсов API платформы

Клиентам разрешено предоставлять реализацию только части интерфейсов API. Условия реализации интерфейсов API описаны в соответствующих контрактах. Интерфейсы, допускающие реализацию клиентами, в документации по Java выделяются явным образом (например, с помощью фразы, аналогичной "Допускает реализацию клиентом"). Клиент может объявить производный интерфейс API только в том случае, если он обладает соответствующими правами.

Реализация общедоступных методов API

См. "Переопределение методов API".

Обращение к полям классов и интерфейсов API

Клиенты могут считывать содержимое полей API, которые как правило объявляются в качестве конечных. В состав некоторых объектов со структурой могут входить общедоступные не конечные поля, к которым клиентам могут быть предоставлены права на чтение и запись.

Преобразование объектов в известный тип API

Преобразование объекта из одного известного типа API в другой тип API (либо условное преобразование с помощью instanceof) допустимо только в том случае, если оно разрешено явным образом в спецификации API. Кроме того, преобразование объекта в класс или интерфейс, не связанный с API, в большинстве случаев недопустимо.

Нарушение правил

Нарушение правил, сознательное или неосознанное, влечет за собой определенные последствия. К сожалению наказание за нарушение правил никем не установлено. В значительной мере соблюдение правил API основано на ответственности за знание и выполнение правил, возлагаемой на каждого клиента.

Контракты, предусмотренные для элементов API, описывают поддерживаемые и сохраненные условия применения. В условиях постоянного развития платформы Eclipse контракты API задают нужное направление изменения. Без учета контрактов все компоненты платформы можно считать неподдерживаемыми, допускающими изменение без дополнительного уведомления в любое время (даже между выпусками и разными операционными системами). Исходный код клиента, не соответствующий правилам, может быть недопустим в других версиях и уровнях исправления платформы, либо при переходе к другой операционной системе, либо при под управлением другого набора модулей, либо при выполнении в другой проекции рабочей среды и т.д. Тем не менее, последствия конкретных нарушений мало кого интересуют. Если вы все же решили нарушить правила, не говорите, что вас не предупреждали. Не следует ожидать чего-либо большего, чем сожаление со стороны окружающих.

С другой стороны, исходный код клиента, соответствующий рассмотренным правилам, должен поддерживать различные версии и уровни исправления платформы, разные базовые операционные системы, а также мирно сосуществовать с другими модулями. Только игра по правилам позволит платформе Eclipse стать стабильной и поддерживаемой основой для создания новых интересных продуктов.