Чи краще повернути ImmutableMap або карту?

Question 1

Скажімо, я пишу метод, який повинен повернути Map . Наприклад:

public Map<String, Integer> foo() {
  return new HashMap<String, Integer>();
}

Подумавши про це деякий час, я вирішив, що немає жодних причин змінювати цю Карту після її створення. Таким чином, я хотів би повернути ImmutableMap .

public Map<String, Integer> foo() {
  return ImmutableMap.of();
}

Чи повинен я залишити тип повернення як загальну карту, чи слід вказати, що я повертаю ImmutableMap?

З одного боку, саме для цього були створені інтерфейси; щоб приховати деталі реалізації.
З іншого боку, якщо я залишу це так, інші розробники можуть пропустити той факт, що цей об’єкт незмінний. Таким чином, я не досягну основної мети незмінних об'єктів; щоб зробити код більш зрозумілим, мінімізуючи кількість об’єктів, які можуть змінюватися. Навіть найгірше, через деякий час хтось може спробувати змінити цей об’єкт, і це призведе до помилки виконання (компілятор про це не попередить).

Question 2

Якщо ви пишете публічний API, і незмінність є важливим аспектом вашого дизайну, я точно визначив би це, якщо назва методу чітко означає, що повернута карта буде незмінною, або повернення конкретного типу карта. На мою думку, згадувати це в javadoc недостатньо.

Оскільки ви, очевидно, використовуєте реалізацію Guava, я подивився документ, і це абстрактний клас, тому він дає вам трохи гнучкості щодо фактичного, конкретного типу.
Якщо ви пишете внутрішній інструмент / бібліотеку, стає набагато прийнятнішим просто повернути звичайний текст Map. Люди будуть знати про внутрішні частини коду, який вони викликають, або принаймні матимуть легкий доступ до нього.

Я б дійшов висновку, що явне - це добре, не залишайте речі на волю випадку.

Question 3

Ви повинні мати ImmutableMapяк тип повернення. Mapмістить методи, які не підтримуються реалізацією ImmutableMap(наприклад put) і позначені @deprecatedв ImmutableMap.

Використання застарілих методів призведе до попередження компілятора, і більшість середовищ розробки ID попереджатимуть, коли люди намагатимуться використовувати застарілі методи.

Це попереджене попередження краще, ніж винятки під час виконання, як перший натяк на те, що щось не так.

Question 4

З іншого боку, якщо я залишу це так, інші розробники можуть пропустити той факт, що цей об’єкт незмінний.

Ви повинні згадати про це в javadocs. Розумієте, розробники їх читають.

Таким чином, я не досягну основної мети незмінних об'єктів; щоб зробити код більш чітким, мінімізуючи кількість об’єктів, які можуть змінюватися. Навіть найгірше, через деякий час хтось може спробувати змінити цей об’єкт, і це призведе до помилки виконання (компілятор про це не попередить).

Жоден розробник не публікує свій код неперевіреним. І коли він протестує його, він отримує виняток, де він не тільки бачить причину, але також файл і рядок, де він намагався записати на незмінну карту.

Зверніть увагу, однак, Mapнезмінним буде лише сам, а не об’єкти, які він містить.

Question 5

якщо я залишу це так, інші розробники можуть пропустити той факт, що цей об'єкт незмінний

Це правда, але інші розробники повинні протестувати свій код і переконатися, що він охоплений.

Тим не менше, у вас є ще 2 варіанти вирішення цієї проблеми:

Використовуйте Javadoc
```
@return a immutable map
```
Виберіть назву описового методу
```
public Map<String, Integer> getImmutableMap()
public Map<String, Integer> getUnmodifiableEntries()
```
Для конкретного випадку ви можете навіть назвати методи краще. Напр
```
public Map<String, Integer> getUnmodifiableCountByWords()
```

Що ще ти можеш зробити ?!

Ви можете повернути a

копію
```
private Map<String, Integer> myMap;

public Map<String, Integer> foo() {
  return new HashMap<String, Integer>(myMap);
}
```
Цей підхід слід використовувати, якщо ви очікуєте, що багато клієнтів модифікують карту і якщо карта містить лише декілька записів.
CopyOnWriteMap

Копіювання на колекції записів зазвичай використовується, коли доводиться мати справу з
паралельністю. Але концепція також допоможе вам у вашій ситуації, оскільки CopyOnWriteMap створює копію внутрішньої структури даних на мутативній операції (наприклад, додавання, видалення).

У цьому випадку вам потрібна тонка обгортка навколо вашої карти, яка делегує всі виклики методів на базову карту, крім мутативних операцій. Якщо викликається мутативна операція, вона створює копію базової карти, і всі подальші виклики будуть делеговані цій копії.

Цей підхід слід використовувати, якщо ви очікуєте, що деякі клієнти змінять карту.

На жаль, у Java такого немає CopyOnWriteMap. Але ви можете знайти третю сторону або реалізувати її самостійно.

Нарешті, слід пам’ятати, що елементи на вашій карті все ще можуть змінюватися.

Question 6

Обов’язково повертає ImmutableMap, виправданням є:

Підпис методу (включаючи тип повернення) повинен бути самодокументованим. Коментарі схожі на обслуговування клієнтів: якщо вашим клієнтам потрібно покластися на них, то ваш основний продукт несправний.
Чи є щось інтерфейсом чи класом, це важливо лише при його розширенні або реалізації. Враховуючи екземпляр (об’єкт), 99% часу клієнтського коду не знатиме чи піклуватися, чи є це щось інтерфейсом чи класом. Спочатку я припустив, що ImmutableMap - це інтерфейс. Лише натиснувши посилання, я зрозумів, що це клас.

Question 7

Це залежить від самого класу. Guava's ImmutableMapне має на меті бути незмінним видом у мінливий клас. Якщо ваш клас незмінний і має якусь структуру, яка в основному є an ImmutableMap, то зробіть тип return ImmutableMap. Однак, якщо ваш клас змінюється, ні. Якщо у вас є це:

public ImmutableMap<String, Integer> foo() {
    return ImmutableMap.copyOf(internalMap);
}

Гуава кожного разу копіюватиме карту. Це повільно. Але якщо internalMapце вже було ImmutableMap, то це цілком нормально.

Якщо ви не обмежуєте свій клас поверненням ImmutableMap, ви можете замість цього повернутись Collections.unmodifiableMapтак:

public Map<String, Integer> foo() {
    return Collections.unmodifiableMap(internalMap);
}

Зверніть увагу, що це незмінний вигляд на карті. Якщо internalMapзміниться, зміниться і кешована копія Collections.unmodifiableMap(internalMap). Однак я все-таки віддаю перевагу цьому для здобувачів.

Question 8

Це не відповідає на точне запитання, але все ж варто подумати, чи взагалі слід повертати карту. Якщо карта незмінна, то основний метод, який потрібно надати, базується на get (ключ):

public Integer fooOf(String key) {
    return map.get(key);
}

Це робить API набагато жорсткішим. Якщо карта насправді потрібна, це може залишитися за клієнтом API, надавши потік записів:

public Stream<Map.Entry<String, Integer>> foos() {
    map.entrySet().stream()
}

Тоді клієнт може створити власну незмінну або змінну карту, як йому потрібно, або додати записи до власної карти. Якщо клієнт повинен знати, чи існує значення, замість нього можна повернути необов’язковий:

public Optional<Integer> fooOf(String key) {
    return Optional.ofNullable(map.get(key));
}

Question 9

Незмінна карта - це тип Карти. Тож залишити тип повернення Map - це нормально.

Щоб користувачі не модифікували повернутий об’єкт, документація методу може описувати характеристики поверненого об’єкта.

Question 10

Це, безперечно, питання думки, але кращою ідеєю тут є використання інтерфейсу для класу карти. Цей інтерфейс не повинен прямо заявляти, що він незмінний, але повідомлення буде однаковим, якщо ви не виставите в інтерфейсі жодного методу встановлення батьківського класу.

Погляньте на наступну статтю:

Енді Гібсон