org.glassfish.jersey.server.monitoring.RequestEvent Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jersey-all Show documentation
Show all versions of jersey-all Show documentation
jersey-all is a rebundled verison of Jersey as one OSGi bundle.
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* 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
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* http://glassfish.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package org.glassfish.jersey.server.monitoring;
import javax.ws.rs.container.ContainerRequestFilter;
import javax.ws.rs.container.ContainerResponseFilter;
import javax.ws.rs.ext.ExceptionMapper;
import org.glassfish.jersey.server.ContainerRequest;
import org.glassfish.jersey.server.ContainerResponse;
import org.glassfish.jersey.server.ExtendedUriInfo;
import org.glassfish.jersey.server.model.Resource;
/**
* An event informing about details of a request processing. The event is created by a Jersey runtime and
* handled by {@link RequestEventListener} (javadoc of listener describes how to register the listener for
* particular request).
*
* The event contains the {@link Type} which distinguishes between types of event. There are various
* properties in the event (accessible by getters) and some of them might be relevant only to specific event types.
*
* Note that internal state of the event must be modified. Even the event is immutable it exposes objects
* which might be mutable and the code of event listener must not change state of these objects.
*
* @author Miroslav Fuksa (miroslav.fuksa at oracle.com)
*/
public interface RequestEvent {
/**
* The type of the event which describes in which request processing phase the event
* is triggered.
*/
public static enum Type {
/**
* The request processing has started. This event type is handled only by
* {@link org.glassfish.jersey.server.monitoring.ApplicationEventListener#onRequest(RequestEvent)} and will
* never be called for {@link RequestEventListener#onEvent(RequestEvent)}.
*/
START,
/**
* The matching of the resource and resource method has started.
*/
MATCHING_START,
/**
* The sub resource locator method is found and it will be called.
* The locator method can be retrieved from {@link #getUriInfo()} by method
* {@link org.glassfish.jersey.server.ExtendedUriInfo#getMatchedResourceLocators()}.
*/
LOCATOR_MATCHED,
/**
* The sub resource has been returned from sub resource locator, model was constructed, enhanced by
* {@link org.glassfish.jersey.server.model.ModelProcessor model processor}, validated and the matching
* is going to be performed on the sub {@link Resource resource}.
* The sub resource can be retrieved from {@link #getUriInfo()} by method
* {@link org.glassfish.jersey.server.ExtendedUriInfo#getLocatorSubResources()}.
*/
SUBRESOURCE_LOCATED,
/**
* The matching has been finished and {@link ContainerRequestFilter container request filters}
* are going to be executed. The request filters can be retrieved from event by
* {@link #getContainerRequestFilters()} method. This method also determines end of the matching
* process and therefore the matching results can be retrieved using {@link #getUriInfo()}.
*/
REQUEST_MATCHED,
/**
* Execution of {@link ContainerRequestFilter container request filters} has been finished.
*/
REQUEST_FILTERED,
/**
* Resource method is going to be executed. The resource method can be extracted from {@link ExtendedUriInfo}
* returned by {@link #getUriInfo()}.
*/
RESOURCE_METHOD_START,
/**
* Resource method execution has finished. In the case of synchronous processing
* the response is not available yet. In the case of asynchronous processing the situation depends on the
* method design and it in some cases on race conditions. In asynchronous cases this event can be
* triggered even after the response is completely processed. Exactly defined, this event
* is triggered when the thread executing the resource method returns from the resource method.
*/
RESOURCE_METHOD_FINISHED,
/**
* {@link ContainerResponseFilter Container response filters} are going to be executed. In this point
* the response is already available and can be retrieved by {@link #getContainerResponse()}. The
* response filters can be retrieved by {@link #getContainerResponseFilters()}.
*
* This phase is executed in the regular response processing but might also been executed for
* processing on response mapped from exceptions by {@link ExceptionMapper exception mappers}.
* In this case the {@link #ON_EXCEPTION} event type precedes this event.
*/
RESP_FILTERS_START,
/**
* Execution of {@link ContainerResponseFilter Container response filters} has finished.
*
* This phase is executed in the regular response processing but might also been executed for
* processing on response mapped from exceptions by {@link ExceptionMapper exception mappers}.
* In this case the {@link #ON_EXCEPTION} event type precedes this event.
*/
RESP_FILTERS_FINISHED,
/**
* Exception has been thrown during the request/response processing. This situation can
* occur in almost all phases of request processing and therefore there is no fixed order of
* events in which this event type can be triggered.
*
* The origin of exception can be retrieved
* by {@link #getExceptionCause()}. This event type can be received even two types in the case
* when first exception is thrown during the standard request processing and the second one
* is thrown during the processing of the response mapped from the exception.
*
* The exception thrown can be retrieved by {@link #getException()}.
*/
ON_EXCEPTION,
/**
* An {@link ExceptionMapper} is successfully found and it is going to be executed. The
* {@code ExceptionMapper} can be retrieved by {@link #getExceptionMapper()}.
*/
EXCEPTION_MAPPER_FOUND,
/**
* Exception mapping is finished. The result of exception mapping can be checked by
* {@link #isResponseSuccessfullyMapped()} which returns true when the exception mapping
* was successful. In this case the new response is available in the {@link #getContainerResponse()}.
*/
EXCEPTION_MAPPING_FINISHED,
/**
* The request and response processing has finished. The result of request processing can be checked
* by {@link #isSuccess()} method. This method is called even when request processing fails and ends
* up with not handled exceptions.
*/
FINISHED
}
/**
* Describes the origin of the exception.
*/
public static enum ExceptionCause {
/**
* An exception was thrown during the standard request and response processing and was not thrown
* from processing of mapped response.
*/
ORIGINAL,
/**
* An exception was thrown during the processing of response
* mapped from {@link ExceptionMapper exception mappers}.
*/
MAPPED_RESPONSE
}
/**
* Returns the {@link Type type} of this event.
*
* @return Request event type.
*/
public Type getType();
/**
* Get the container request. The container request is available for all event types. Returned
* request must not be modified by the {@link RequestEventListener request event listener}.
*
* @return The non-null container request.
*/
public ContainerRequest getContainerRequest();
/**
* Get the container response. The response is available only for certain {@link Type event types}. The
* returned response might vary also on the event type. The getter returns always the latest response being
* processed. So, for example for event {@link Type#EXCEPTION_MAPPING_FINISHED} event type the method
* returns mapped response and not the original response created from execution of the resource method.
*
* @return Latest response being processed or {@link null} if no response has been produced yet.
*/
public ContainerResponse getContainerResponse();
/**
* Get the latest exception, if any, thrown by the request and response processing. When this method
* returns not null value, the method {@link #getExceptionCause()} returns the origin of the exception.
*
* @return Exception thrown or {@link null} if no exception has been thrown.
*/
public Throwable getException();
/**
* Get the {@link ExtendedUriInfo extended uri info} associated with this request. This method returns
* null for {@link Type#START} event. The returned {@code ExtendedUriInfo} can be used to retrieve
* information relevant to many event types (especially event types describing the matching process).
*
* @return Extended uri info or {@link null} if it is not available yet.
*/
public ExtendedUriInfo getUriInfo();
/**
* Get the {@link ExceptionMapper} that was found and used during the exception mapping phase.
*
* @return Exception mapper or {@link null} if no exception mapper was found or even needed.
*/
public ExceptionMapper getExceptionMapper();
/**
* Get {@link ContainerRequestFilter container request filters} used during the request filtering
* phase.
*
* @return Container request filters or {@link null} if no filters were used yet.
*/
public Iterable getContainerRequestFilters();
/**
* Get {@link ContainerResponseFilter container response filters} used during the response filtering
* phase.
*
* @return Container response filter or {@link null} if no filters were used yet.
*/
public Iterable getContainerResponseFilters();
/**
* Return {@code true} if the request and response has been successfully processed. Response is successfully
* processed when the response code is smaller than 400 and response was successfully written. If the exception
* occurred but was mapped into a response with successful response code and written, this method returns
* {@code true}.
*
* @return True if the response was successfully processed.
*/
public boolean isSuccess();
/**
* Returns {@code true} if the response was successfully mapped from an exception
* by {@link ExceptionMapper exception mappers}. When exception mapping phase failed or when
* no exception was thrown at all the, the method returns false. This method is convenient when
* handling the {@link Type#EXCEPTION_MAPPING_FINISHED} event type.
*
* @return True if the exception occurred and it was successfully mapped into a response.
*/
public boolean isResponseSuccessfullyMapped();
/**
* Get the {@link ExceptionCause exception cause}. This method is relevant only in cases when
* {@link #getException()} returns non-null value (for example when handling {@link Type#ON_EXCEPTION})
* event type.
*
* @return Exception cause of the latest exception or {@code null} if no exception has occurred.
*/
public ExceptionCause getExceptionCause();
/**
* Returns {@code true} if the response has been successfully written. {@code true} is returned
* even for cases when the written response contains error response code.
*
* @return {@code true} if the response was successfully written;{@code false} when the response
* has not been written yet or when writing of response failed.
*/
public boolean isResponseWritten();
}