Проект API

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

Параметры

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

Далее, следует всегда использовать наименее специфичный тип, который имеет смысл. Например, не требуйте a List или a Set если a Collection сделал бы. Не то, чтобы никогда недопустимо требовать a List или a Set на вводе; это корректно, чтобы сделать так, если метод зависит от свойства одного из этих интерфейсов. Например, многие из алгоритмов, обеспеченных платформой Java, требуют a List на вводе, потому что они зависят от факта, что списки упорядочиваются. Как правило, однако, лучшие типы, чтобы использовать на вводе являются самыми общими: Collection и Map.

Возвращаемые значения

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

Например, можно было вообразить пакет обработки изображений, вызванный ImageList, это возвратило объекты нового class, который реализует List. В дополнение к List операции, ImageList мог поддерживать любые специализированные операции, которые казались требуемыми. Например, это могло бы обеспечить indexImage работа, которая возвратила изображение, содержащее изображения миниатюры каждой графики в ImageList. Является критическим отметить это, даже если API оснащает ImageList экземпляры на выводе, это должно принять произвольный Collection (или возможно List) экземпляры на вводе.

В одном смысле у возвращаемых значений должно быть противоположное поведение входных параметров: Лучше возвращать самый определенный применимый интерфейс набора, а не самое общее. Например, если Вы уверены, что будете всегда возвращать a SortedMap, следует дать соответствующему методу тип возврата SortedMap вместо Map. SortedMap экземпляры являются более отнимающими много времени, чтобы создать чем обычный Map экземпляры и также более мощны. Учитывая, что Ваш модуль уже инвестировал время, чтобы создать a SortedMap, это проявляет здравый смысл предоставить пользовательский доступ к его увеличенному питанию. Кроме того пользователь будет в состоянии передать возвращенный объект к методам то требование a SortedMap, так же как те, которые принимают любого Map.

API наследства

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

Если возможный, модифицируйте свой тип набора наследства, чтобы реализовать один из стандартных интерфейсов набора. Затем все наборы, которые Вы возвращаете, будут взаимодействовать гладко с другими основанными на наборе API. Если это невозможно (например, потому что один или больше существующего ранее конфликта подписей типа со стандартными интерфейсами набора), определите адаптер class, который обертывает один из Ваших объектов наборов наследства, позволяя его функционировать как стандартный набор. ( Adapter class является примером пользовательской реализации.)

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