J-176 @beta API clean-up

Change-Id: I42cda376bba2ac46faadc96443e02dfbe57d2f0b Signed-off-by: Marek Potociar <[email protected]>
ylong · Jul 31, 2014 · 5d921d9 · 5d921d9
1 parent d03b4d0
commit 5d921d9
Show file tree

Hide file tree

Showing 7 changed files with 64 additions and 24 deletions.
diff --git a/...t/src/main/java/org/glassfish/jersey/client/authentication/HttpAuthenticationFeature.java b/...t/src/main/java/org/glassfish/jersey/client/authentication/HttpAuthenticationFeature.java
@@ -1,7 +1,7 @@
 /*
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
- * Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013-2014 Oracle and/or its affiliates. All rights reserved.
  *
  * The contents of this file are subject to the terms of either the GNU
  * General Public License Version 2 only ("GPL") or the Common Development
@@ -42,7 +42,6 @@
 import javax.ws.rs.core.Feature;
 import javax.ws.rs.core.FeatureContext;
 
-import org.glassfish.jersey.Beta;
 
 /**
  * Features that provides Http Basic and Digest client authentication (based on RFC 2617).
@@ -141,9 +140,8 @@
  *
  * @author Miroslav Fuksa (miroslav.fuksa at oracle.com)
  *
- * @since 2.5 (beta)
+ * @since 2.5
  */
-@Beta
 public class HttpAuthenticationFeature implements Feature {
 
     /**

diff --git a/...rc/main/java/org/glassfish/jersey/server/internal/monitoring/MonitoringEventListener.java b/...rc/main/java/org/glassfish/jersey/server/internal/monitoring/MonitoringEventListener.java
@@ -53,8 +53,7 @@
 import org.glassfish.jersey.server.model.ResourceMethod;
 import org.glassfish.jersey.server.monitoring.ApplicationEvent;
 import org.glassfish.jersey.server.monitoring.ApplicationEventListener;
-import org.glassfish.jersey.server.monitoring.ExtendedMonitoringStatisticsListener;
-import org.glassfish.jersey.server.monitoring.MonitoringStatisticsListener;
+import org.glassfish.jersey.server.monitoring.DestroyListener;
 import org.glassfish.jersey.server.monitoring.RequestEvent;
 import org.glassfish.jersey.server.monitoring.RequestEventListener;
 import org.glassfish.jersey.uri.UriTemplate;
@@ -227,14 +226,12 @@ public void onEvent(final ApplicationEvent event) {
                 }
 
                 // onDestroy
-                final List<MonitoringStatisticsListener> listeners = serviceLocator
-                        .getAllServices(MonitoringStatisticsListener.class);
+                final List<DestroyListener> listeners =
+                        serviceLocator.getAllServices(DestroyListener.class);
 
-                for (final MonitoringStatisticsListener listener : listeners) {
+                for (final DestroyListener listener : listeners) {
                     try {
-                        if (listener instanceof ExtendedMonitoringStatisticsListener) {
-                            ((ExtendedMonitoringStatisticsListener) listener).onDestroy();
-                        }
+                        listener.onDestroy();
                     } catch (final Exception e) {
                         LOGGER.log(Level.WARNING,
                                 LocalizationMessages.ERROR_MONITORING_STATISTICS_LISTENER_DESTROY(listener.getClass()), e);

diff --git a/...ExtendedMonitoringStatisticsListener.java → ...ey/server/monitoring/DestroyListener.java b/...ExtendedMonitoringStatisticsListener.java → ...ey/server/monitoring/DestroyListener.java
@@ -1,7 +1,7 @@
 /*
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
- * Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013-2014 Oracle and/or its affiliates. All rights reserved.
  *
  * The contents of this file are subject to the terms of either the GNU
  * General Public License Version 2 only ("GPL") or the Common Development
@@ -42,22 +42,37 @@
 import javax.ws.rs.ConstrainedTo;
 import javax.ws.rs.RuntimeType;
 
-import org.glassfish.jersey.Beta;
+import org.glassfish.jersey.spi.Contract;
 
 /**
- * Extension of the {@link MonitoringStatisticsListener} which allows to listen to the event
- * of destroying the application.
+ * A listener contract that allows any registered implementation class to receive application destroy events.
+ * <p>
+ * The {@link #onDestroy()} method is called when application is being destroyed and after all the pending
+ * {@link MonitoringStatisticsListener#onStatistics(MonitoringStatistics) monitoring statistics events} have been
+ * dispatched and processed.
+ * </p>
+ * <p>
+ * The advantage of using {@code DestroyListener} over using {@link ApplicationEventListener} directly to check for the
+ * {@link ApplicationEvent.Type#DESTROY_FINISHED} event is, that the {@link #onDestroy()}
+ * method is guaranteed to be called only AFTER all the {@code MonitoringStatisticsListener#onStatistics()} events have been
+ * dispatched and processed, as opposed to using the {@code ApplicationEventListener} directly, in which case some monitoring
+ * statistics events may still be concurrently fired after the {@code DESTROY_FINISHED} event has been dispatched
+ * (due to potential race conditions).
+ * </p>
  *
- * @since 2.5
  * @author Miroslav Fuksa (miroslav.fuksa at oracle.com)
+ * @author Adam Lindenthal (adam.lindenthal at oracle.com)
+ * @see MonitoringStatisticsListener
+ * @since 2.12
  */
-@Beta
+@Contract
 @ConstrainedTo(RuntimeType.SERVER)
-public interface ExtendedMonitoringStatisticsListener extends MonitoringStatisticsListener {
+public interface DestroyListener {
     /**
      * The method is called when application is destroyed. Use this method release resources of
-     * the listener. This method will be called in the thread safe way (synchronously and by a single)
-     * according to other methods from this or parent interface.
+     * the listener. This method will be called in the thread safe way (synchronously and by a single thread)
+     * according to other methods from the related {@link org.glassfish.jersey.server.monitoring.MonitoringStatisticsListener}
+     * interface.
      */
     public void onDestroy();
-}
+}
diff --git a/...er/src/main/java/org/glassfish/jersey/server/monitoring/MonitoringStatisticsListener.java b/...er/src/main/java/org/glassfish/jersey/server/monitoring/MonitoringStatisticsListener.java
@@ -61,6 +61,7 @@
  * <p/>
  *
  * @author Miroslav Fuksa (miroslav.fuksa at oracle.com)
+ * @see DestroyListener
  */
 @Contract
 @ConstrainedTo(RuntimeType.SERVER)

diff --git a/docs/src/main/docbook/jersey.ent b/docs/src/main/docbook/jersey.ent
@@ -431,6 +431,7 @@
 <!ENTITY jersey.server.monitoring.MonitoringStatistics "<link xlink:href='&jersey.javadoc.uri.prefix;/server/monitoring/MonitoringStatistics.html'>MonitoringStatistics</link>">
 <!ENTITY jersey.server.monitoring.MonitoringStatistics "<link xlink:href='&jersey.javadoc.uri.prefix;/server/monitoring/MonitoringStatistics.html'>MonitoringStatistics</link>">
 <!ENTITY jersey.server.monitoring.MonitoringStatisticsListener "<link xlink:href='&jersey.javadoc.uri.prefix;/server/monitoring/MonitoringStatisticsListener.html'>MonitoringStatisticsListener</link>">
+<!ENTITY jersey.server.monitoring.DestroyListener "<link xlink:href='&jersey.javadoc.uri.prefix;/server/monitoring/DestroyListener.html'>DestroyListener</link>">
 <!ENTITY jersey.server.monitoring.RequestEvent "<link xlink:href='&jersey.javadoc.uri.prefix;/server/monitoring/RequestEvent.html'>RequestEvent</link>">
 <!ENTITY jersey.server.monitoring.RequestEventListener "<link xlink:href='&jersey.javadoc.uri.prefix;/server/monitoring/RequestEventListener.html'>RequestEventListener</link>">
 <!ENTITY jersey.server.monitoring.ResourceMXBean "<link xlink:href='&jersey.javadoc.uri.prefix;/server/monitoring/ResourceMXBean.html'>ResourceMXBean</link>">
@@ -757,6 +758,7 @@
 <!ENTITY lit.jersey.server.monitoring.MonitoringStatistics "<literal>MonitoringStatistics</literal>">
 <!ENTITY lit.jersey.server.monitoring.MonitoringStatistics "<literal>MonitoringStatistics</literal>">
 <!ENTITY lit.jersey.server.monitoring.MonitoringStatisticsListener "<literal>MonitoringStatisticsListener</literal>">
+<!ENTITY lit.jersey.server.monitoring.DestroyListener "<literal>DestroyListener</literal>">
 <!ENTITY lit.jersey.server.monitoring.RequestEvent "<literal>RequestEvent</literal>">
 <!ENTITY lit.jersey.server.monitoring.RequestEventListener "<literal>RequestEventListener</literal>">
 <!ENTITY lit.jersey.server.monitoring.ResourceMXBean "<literal>ResourceMXBean</literal>">

diff --git a/docs/src/main/docbook/migration.xml b/docs/src/main/docbook/migration.xml
@@ -52,6 +52,33 @@
          xml:id="migration">
     <title>Migration Guide</title>
 
+    <section xml:id="mig-2.12">
+        <title>Migrating from Jersey 2.11 to 2.12</title>
+        <section xml:id="mig-2.12-highlights">
+            <title>Release 2.12 Highlights</title>
+            Following experimental APIs have been promoted to become part of public Jersey API:
+            <itemizedlist>
+                <listitem>
+                    <para>
+                        Jersey client-side &jersey.client.HttpAuthenticationFeature; API.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+                        Jersey server-side &jersey.server.monitoring.DestroyListener; (formerly
+                        <literal>ExtendedMonitoringStatisticsListener</literal>), which has been slightly refactored and
+                        is now a separate interface (e.g. not extending <literal>MonitoringStatisticsListener</literal>),
+                        hence providing better compatibility with lambdas.
+                    </para>
+                </listitem>
+            </itemizedlist>
+
+            These APIs are now part of the official public Jersey 2.x API.
+        </section>
+    </section>
+
+
+
     <section xml:id="mig-2.11">
         <title>Migrating from Jersey 2.10 to 2.11</title>
 

diff --git a/...src/test/java/org/glassfish/jersey/tests/e2e/server/monitoring/StatisticsDestroyTest.java b/...src/test/java/org/glassfish/jersey/tests/e2e/server/monitoring/StatisticsDestroyTest.java
@@ -50,7 +50,7 @@
 
 import org.glassfish.jersey.server.ResourceConfig;
 import org.glassfish.jersey.server.ServerProperties;
-import org.glassfish.jersey.server.monitoring.ExtendedMonitoringStatisticsListener;
+import org.glassfish.jersey.server.monitoring.DestroyListener;
 import org.glassfish.jersey.server.monitoring.MonitoringStatistics;
 import org.glassfish.jersey.server.monitoring.MonitoringStatisticsListener;
 import org.glassfish.jersey.server.spi.AbstractContainerLifecycleListener;
@@ -184,7 +184,7 @@ protected TestContainerFactory getTestContainerFactory() throws TestContainerExc
     }
 
     public static class StatisticsListener extends AbstractContainerLifecycleListener
-            implements ExtendedMonitoringStatisticsListener {
+            implements MonitoringStatisticsListener, DestroyListener {
 
         public static boolean ON_SHUTDOWN_CALLED = false;
         public static boolean ON_STATISTICS_CALLED = false;