Javadocで稀によく見る（オプションの操作）の謎

# 1.はじめに

Javadocを眺めていると目にすることのある

| 修飾子と型 | メソッドと説明 |
|:-:|:-:|
| 〇〇  |  hoge(○○ ××) <br>～～～～～～<b>（オプションの操作）</b>。 |




例：[List(Java Platform SE8)](https://docs.oracle.com/javase/jp/8/docs/api/java/util/List.html), [Set(Java Platform SE8)](https://docs.oracle.com/javase/jp/8/docs/api/java/util/Set.html)


この意味について気にはなっていたもののググっても解説が見当たらなかった。
（もしかして常識過ぎて誰も解説してないのか。。。？）


# 2.規約
単刀直入に言うと以下のものが規約として存在する。
>・インタフェースの実装においてオプションであるメソッドは、実装されない場合にUnsupportedOperationExceptionをスローします。どのメソッドがオプションであるかは、メソッドの説明の最後に「（オプション）」と示すことで、随時示していきます。


以上
「プログラミング言語Java 第四版」東京電機大学出版局,ケン・アーノルド　ジェームズ・ゴスリン　デビッド・ホームズ著,柴田芳樹訳,第四版１刷発行,502p
からの引用

# 3.Listインターフェースの例
ListインターフェースのJavadocには以下の10個のメソッドの説明に（オプションの操作）と書かれている。

| 修飾子と型 | メソッドと説明 |
|:-:|:-:|
| boolean  |  <b>add(E e)</b> <br>指定された要素をこのリストの最後に追加します(オプションの操作)。 |
| void  | <b>add(int index, E element)</b><br>このリスト内の指定された位置に、指定された要素を挿入します(オプションの操作)。  |
| boolean  | <b>addAll(Collection<? extends E> c)</b>指定されたコレクション内のすべての要素を、指定されたコレクションのイテレータによって返される順序で、このリストの最後に追加します(オプションの操作)。  |
| boolean  |  <b>addAll(int index, Collection<? extends E> c)</b><br>指定されたコレクション内のすべての要素を、このリストの指定された位置に挿入します(オプションの操作)。  |
| void  | <b>clear()</b><br>すべての要素をこのリストから削除します(オプションの操作)。  |
| E  | <b>remove(int index)</b><br>このリスト内の指定された位置にある要素を削除します(オプションの操作)。  |
| boolean  | <b>remove(Object o)</b><br>指定された要素がこのリストにあれば、その最初のものをリストから削除します(オプションの操作)。  |
| boolean  |<b>removeAll(Collection<?> c)</b><br>このリストから、指定されたコレクションに含まれる要素をすべて削除します(オプションの操作)。   |
|  boolean |  <b>retainAll(Collection<?> c)</b><br>このリスト内で、指定されたコレクションに含まれている要素だけを保持します(オプションの操作)。 |
| E  |  <b>set(int index, E element)</b><br>このリスト内の指定された位置にある要素を、指定された要素に置き換えます(オプションの操作)。 |

規約によるとこれらのメソッドをListを実装したクラスのインスタンスに使った場合、「コンパイルは通るが実行時に例外が起きる」という可能性がある。

例えば、たびたび初心者が引っかかることになる
Arrays.asList(T...)や修正不可能なリストを返すCollections.unmodifiableList(list)で返されるリストがそれにあたる。

# 4.Arrays.asList(T...)
散々ネット上で書かれてことではあるがArrays.asList(T...)で返されるリストにはaddやremoveができない。

参考：
[Java - Arrays.asList の注意点](https://qiita.com/HomMarkHunt/items/c0172bd6c9801c5768d2),
[Arrays.asList() は単なる配列のラッパを返すだけなので、要素の追加も削除もできません](http://etc9.hatenablog.com/entry/2017/04/17/232505)

このメソッドで返されるのはListを実装した（より正確にはListを実装したAbstractListを継承した）java.util.Arrays内staticクラスのArrayListである。（java.util.ArrayListとは別物）

```java

public static void main(String... args){
    List<String list=Arrays.asList("aaa","bbb");
    System.out.println(list.getClass());
    //->class java.util.Arrays$ArrayList
}
```

ソースコード
[Github：jdk8/java/util/Arrays.java](https://github.com/ZenOfAutumn/jdk8/blob/master/java/util/Arrays.java)

読んでわかる通りadd()やremove()のメソッドがOverrideされていない。
よって親クラスのメソッドが呼ばれるが、そこにはこう書かれているので無事UnsupportOperationExceptionがスローされる。


```java:AbstractList.java
public void add(int index, E element) {
    throw new UnsupportedOperationException();
}
```

ただし（オプションの操作）と記載されているメソッドのうちset()は正しく動くようにOverrideされているのでこのメソッドは例外を起こさずに使うことができる。
# 5.Collections.unmodifiableList(List)
これはjava.util.Collections内のstaticクラスであるUnmodifiableListかUnmodifiableRandomAccessListを返している。

[Github：jdk8/java/util/Collections.java](https://github.com/ZenOfAutumn/jdk8/blob/master/java/util/Collections.java)

見てわかるとおり、このクラスはオプションの操作のどのメソッドもUnsupportOperationExceptionが投げられる。


# 6.SubList系
subListメソッドはListインターフェースで宣言されている。よく見るやつを紹介する。

## java.util.ArrayList$SubList
最もよく使われるList実装であろうArrayListのsubListメソッドを使うときに返される。オプション操作のうちすべてのメソッドを使うことができる。

## java.util.ImmutableCollections$SubList
java9で追加されたList.ofで返されるListNクラス（これはImutableCollectionsクラスのstatic内部クラス）のsubListメソッドを使うと返される。全部ダメ！

# 7.まとめ
まあ謎の記述が理解できてよかったねって話なんですけど、、、

static内部クラスはJavadocに出ないのでオプションの操作のうちどの操作が許される操作（Arras.asListのset()など）なのかがソース見ないと分からないのは辛くないんですかね...?