Summary
-------

The classes `javax.management.AttributeList`, and `javax.management.relation.RoleList` and `UnresolvedRoleList`, have a historical feature where they accept objects of the wrong type, and only check for wrong objects when (and after) the "asList()" method is called.  This feature should be removed, and these classes should never accept the wrong kind of Object.

Problem
-------

These three classes have unnecessary complexity around type-checking 
Objects which are added.  There is no need for these classes to hold Objects of the wrong type.

This feature was added between JDK1.5 and JDK1.6, for compatibility.   The compatibility issue was only ever minor: prior JMX releases 1.2 and 1.3 and the release in JDK 1.5 had methods which accepted the specific class.  Therefore even in JDK1.6, there was no expectation that these classes could hold anything other than the specific type.

Adding alien Objects has been specifically strongly discouraged in the AttributeList API docs, and should now be illegal, and the unnecessary complexity removed.

Solution
--------



Simply enforce the checking of types in these classes.  Fail fast, in the obscure case that incorrect types are used.




Specification
-------------

API changes:  API doc text updates.  No disruptive or incompatible API changes.

* In the class AttributeList:

Remove the text:
```
For compatibility reasons, it is possible, though highly discouraged, to add objects to an AttributeList that are not instances of Attribute. However, an AttributeList can be made type-safe, which means that an attempt to add an object that is not an Attribute will produce an IllegalArgumentException. An AttributeList becomes type-safe when the method asList() is called on it.
```

Replace with:

```
 * <p>It is not permitted to add objects to an {@code AttributeList} that are
 * not instances of {@code Attribute}.  This will produce an {@code IllegalArgumentException}
 * when calling methods in this class, or when using {@code listIterator} and {@code add} or {@code set}.</p>
```

In the "asList()" method, remove:
"If this method has ever been called on a given AttributeList instance, a subsequent attempt to add an object to that instance which is not an Attribute will fail with an IllegalArgumentException. For compatibility reasons, an AttributeList on which this method has never been called does allow objects other than Attributes to be added."

Update the wording of some throws messages for IllegalArgumentException.


* In the class javax.management.relation.RoleList:

Similarly to AttributeList, add: 

```
 * <p>It is not permitted to add objects to a {@code RoleList} that are
 * not instances of {@code Role}.  This will produce an {@code IllegalArgumentException}
 * when calling methods in this class, or when using {@code listIterator} and {@code add} or {@code set}.</p>
```

Remove the same wording from the "asList()" method.

Updatewording of some throws messages for IllegalArgumentException.

Add inheritdoc tags for clarity.


* In the class javax.management.relation.RoleUnresolvedList

Similarly to AttributeList, add: 

```
 * <p>It is not permitted to add objects to a {@code RoleUnresolvedList} that are
 * not instances of {@code RoleUnresolved}.  This will produce an {@code IllegalArgumentException}
 * when calling methods in this class, or when using {@code listIterator} and {@code add} or {@code set}.</p>
```

Remove the same wording from the "asList()" method.

Change wording of some throws messages for IllegalArgumentException.

Add inheritdoc tags for clarity.


In the attached specdiff_8359809.zip file, see:

AttributeList.html

relation/RoleList.html

relation/RoleUnresolvedList.html



Github reference: https://github.com/openjdk/jdk/pull/25856