8023447: change specification to allow RMI activation to be optional

Reviewed-by: darcy, alanb, olagneau

src/share/classes/java/rmi/activation/Activatable.java

 /*
- * Copyright (c) 1997, 2005, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -93,6 +93,8 @@ public abstract class Activatable extends RemoteServer {
      * @exception RemoteException if either of the following fails:
      * a) registering the object with the activation system or b) exporting
      * the object to the RMI runtime.
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation.
      * @since 1.2
      **/
     protected Activatable(String location,
@@ -143,6 +145,8 @@ public abstract class Activatable extends RemoteServer {
      * @exception RemoteException if either of the following fails:
      * a) registering the object with the activation system or b) exporting
      * the object to the RMI runtime.
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation.
      * @since 1.2
      **/
     protected Activatable(String location,
@@ -175,6 +179,8 @@ public abstract class Activatable extends RemoteServer {
      * @param port the port number on which the object is exported
      * @exception RemoteException if exporting the object to the RMI
      * runtime fails
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @since 1.2
      */
     protected Activatable(ActivationID id, int port)
@@ -206,6 +212,8 @@ public abstract class Activatable extends RemoteServer {
      * @param ssf the server-side socket factory for receiving remote calls
      * @exception RemoteException if exporting the object to the RMI
      * runtime fails
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @since 1.2
      */
     protected Activatable(ActivationID id, int port,
@@ -239,6 +247,8 @@ public abstract class Activatable extends RemoteServer {
      * is not registered with the activation system
      * @exception ActivationException if activation system is not running
      * @exception RemoteException if remote call fails
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @since 1.2
      */
     public static Remote register(ActivationDesc desc)
@@ -273,6 +283,8 @@ public abstract class Activatable extends RemoteServer {
      * already be inactive)
      * @exception ActivationException if group is not active
      * @exception RemoteException if call informing monitor fails
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @since 1.2
      */
     public static boolean inactive(ActivationID id)
@@ -290,6 +302,8 @@ public abstract class Activatable extends RemoteServer {
      * @exception UnknownObjectException if object (<code>id</code>) is unknown
      * @exception ActivationException if activation system is not running
      * @exception RemoteException if remote call to activation system fails
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @since 1.2
      */
     public static void unregister(ActivationID id)
@@ -334,6 +348,8 @@ public abstract class Activatable extends RemoteServer {
      * the wrong group
      * @exception ActivationException if activation group is not active
      * @exception RemoteException if object registration or export fails
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @since 1.2
      **/
     public static ActivationID exportObject(Remote obj,
@@ -407,6 +423,8 @@ public abstract class Activatable extends RemoteServer {
      * descriptor with the activation system
      * @exception ActivationException if activation group is not active
      * @exception RemoteException if object registration or export fails
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @since 1.2
      **/
     public static ActivationID exportObject(Remote obj,
@@ -473,6 +491,8 @@ public abstract class Activatable extends RemoteServer {
      * @param port the port on which the object is exported (an anonymous
      * port is used if port=0)
      * @exception RemoteException if object export fails
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @since 1.2
      */
     public static Remote exportObject(Remote obj,
@@ -503,6 +523,8 @@ public abstract class Activatable extends RemoteServer {
      * remote object
      * @param ssf the server-side socket factory for receiving remote calls
      * @exception RemoteException if object export fails
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @since 1.2
      */
     public static Remote exportObject(Remote obj,
@@ -531,6 +553,8 @@ public abstract class Activatable extends RemoteServer {
      * @return true if operation is successful, false otherwise
      * @exception NoSuchObjectException if the remote object is not
      * currently exported
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @since 1.2
      */
     public static boolean unexportObject(Remote obj, boolean force)

src/share/classes/java/rmi/activation/ActivationDesc.java

 /*
- * Copyright (c) 1997, 2005, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -105,6 +105,8 @@ public final class ActivationDesc implements Serializable {
      * @param data the object's initialization (activation) data contained
      * in marshalled form.
      * @exception ActivationException if the current group is nonexistent
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @since 1.2
      */
     public ActivationDesc(String className,
@@ -142,6 +144,8 @@ public final class ActivationDesc implements Serializable {
      * <code>true</code> does not force an initial immediate activation of
      * a newly registered object;  initial activation is lazy.
      * @exception ActivationException if the current group is nonexistent
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @since 1.2
      */
     public ActivationDesc(String className,
@@ -176,6 +180,8 @@ public final class ActivationDesc implements Serializable {
      * @param data  the object's initialization (activation) data contained
      * in marshalled form.
      * @exception IllegalArgumentException if <code>groupID</code> is null
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @since 1.2
      */
     public ActivationDesc(ActivationGroupID groupID,
@@ -208,6 +214,8 @@ public final class ActivationDesc implements Serializable {
      * <code>true</code> does not force an initial immediate activation of
      * a newly registered object;  initial activation is lazy.
      * @exception IllegalArgumentException if <code>groupID</code> is null
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @since 1.2
      */
     public ActivationDesc(ActivationGroupID groupID,

src/share/classes/java/rmi/activation/ActivationGroup.java

 /*
- * Copyright (c) 1997, 2005, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -133,6 +133,8 @@ public abstract class ActivationGroup
      *
      * @param   groupID the group's identifier
      * @throws  RemoteException if this group could not be exported
+     * @throws  UnsupportedOperationException if and only if activation is
+     *          not supported by this implementation
      * @since   1.2
      */
     protected ActivationGroup(ActivationGroupID groupID)
@@ -267,6 +269,8 @@ public abstract class ActivationGroup
      * (Note: The default implementation of the security manager
      * <code>checkSetFactory</code>
      * method requires the RuntimePermission "setFactory")
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @see SecurityManager#checkSetFactory
      * @since 1.2
      */
@@ -345,6 +349,8 @@ public abstract class ActivationGroup
     /**
      * Returns the current activation group's identifier.  Returns null
      * if no group is currently active for this VM.
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @return the activation group's identifier
      * @since 1.2
      */
@@ -394,6 +400,8 @@ public abstract class ActivationGroup
      * (Note: The default implementation of the security manager
      * <code>checkSetFactory</code>
      * method requires the RuntimePermission "setFactory")
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @see #getSystem
      * @see SecurityManager#checkSetFactory
      * @since 1.2
@@ -428,6 +436,8 @@ public abstract class ActivationGroup
      * @exception ActivationException if activation system cannot be
      *  obtained or is not bound
      * (means that it is not running)
+     * @exception UnsupportedOperationException if and only if activation is
+     * not supported by this implementation
      * @see #setSystem
      * @since 1.2
      */

src/share/classes/java/rmi/activation/ActivationGroupID.java

 /*
- * Copyright (c) 1997, 1999, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -63,6 +63,8 @@ public class ActivationGroupID implements java.io.Serializable {
      * Constructs a unique group id.
      *
      * @param system the group's activation system
+     * @throws UnsupportedOperationException if and only if activation is
+     *         not supported by this implementation
      * @since 1.2
      */
     public ActivationGroupID(ActivationSystem system) {

src/share/classes/java/rmi/activation/ActivationID.java

 /*
- * Copyright (c) 1997, 2005, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -90,6 +90,8 @@ public class ActivationID implements Serializable {
      *
      * @param activator reference to the activator responsible for
      * activating the object
+     * @throws UnsupportedOperationException if and only if activation is
+     *         not supported by this implementation
      * @since 1.2
      */
     public ActivationID(Activator activator) {

src/share/classes/java/rmi/activation/package.html

 <!--
- Copyright (c) 1998, 1999, Oracle and/or its affiliates. All rights reserved.
+ Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 
  This code is free software; you can redistribute it and/or modify it
@@ -31,6 +31,15 @@ Provides support for RMI Object Activation.  A remote
 object's reference can be made ``persistent'' and later activated into a
 ``live'' object using the RMI activation mechanism.
 
+<p>Implementations are not required to support the activation
+mechanism. If activation is not supported by this implementation,
+several specific activation API methods are all required to throw
+{@code UnsupportedOperationException}. If activation is supported by this
+implementation, these methods must never throw {@code
+UnsupportedOperationException}. These methods are denoted by the
+presence of an entry for {@code UnsupportedOperationException} in the
+<strong>Throws</strong> section of each method's specification.
+
 <!--
 <h2>Package Specification</h2>