Spec-Zone .ru спецификации, руководства, описания, API

javax.servlet
Интерфейс AsyncContext

public interface AsyncContext

Класс, представляющий контекст выполнения для асинхронной работы, которая инициировалась на ServletRequest.

AsyncContext создается и инициализируется звонком ServletRequest#startAsync() или ServletRequest#startAsync(ServletRequest, ServletResponse). Повторные вызовы этих методов возвратят тот же самый экземпляр AsyncContext, повторно инициализированный как соответствующий.

Когда асинхронная работа имеет синхронизированный, контейнер должен пробежать эти шаги:

1. Вызовите в их onTimeout метод, все AsyncListener экземпляры, зарегистрированные в ServletRequest, на котором инициировалась асинхронная работа.
2. Если ни одного из слушателей не вызывают complete() или любой из dispatch() методы, выполните ошибку, диспетчеризируют с кодом состояния, равным HttpServletResponse.SC_INTERNAL_SERVER_ERROR.
3. Если никакая ошибочная страница соответствия не была найдена, или ошибочная страница не вызывала complete() или любой из dispatch() методы, вызвать complete().

С тех пор:

Сервлет 3.0

Полевая Сводка

static java.lang.String	ASYNC_CONTEXT_PATH Имя запроса приписывает, под которым исходный путь контекста делается доступным для цели a dispatch(String) или dispatch(ServletContext,String)
static java.lang.String	ASYNC_PATH_INFO Имя запроса приписывает, под которым исходная информация пути делается доступной для цели a dispatch(String) или dispatch(ServletContext,String)
static java.lang.String	ASYNC_QUERY_STRING Имя запроса приписывает, под которым исходная строка запроса делается доступной для цели a dispatch(String) или dispatch(ServletContext,String)
static java.lang.String	ASYNC_REQUEST_URI Имя запроса приписывает, под которым исходный URI запроса делается доступным для цели a dispatch(String) или dispatch(ServletContext,String)
static java.lang.String	ASYNC_SERVLET_PATH Имя запроса приписывает, под которым исходный путь сервлета делается доступным для цели a dispatch(String) или dispatch(ServletContext,String)

Сводка метода

void	addListener(AsyncListener listener) Регистрирует данный AsyncListener с новым асинхронным циклом, который был запущен звонком в один из ServletRequest#startAsync методы.
void	addListener(AsyncListener listener, ServletRequest servletRequest, ServletResponse servletResponse) Регистрирует данный AsyncListener с новым асинхронным циклом, который был запущен звонком в один из ServletRequest#startAsync методы.
void	complete() Завершает асинхронную работу, которая была запущена по запросу, который привык к initialze этот AsyncContext, закрывая ответ, который использовался, чтобы инициализировать этот AsyncContext.
<T extends AsyncListener> T	createListener(java.lang.Class<T> clazz) Инстанцирует данного AsyncListener class.
void	dispatch() Диспетчеризирует запрос и объекты ответа этого AsyncContext к контейнеру сервлета.
void	dispatch(ServletContext context, java.lang.String path) Диспетчеризирует запрос и объекты ответа этого AsyncContext к данному path, определяющему контекст к данному context.
void	dispatch(java.lang.String path) Диспетчеризирует запрос и объекты ответа этого AsyncContext к данному path.
ServletRequest	getRequest() Получает запрос, который использовался, чтобы инициализировать этот AsyncContext, вызывая ServletRequest#startAsync() или ServletRequest#startAsync(ServletRequest, ServletResponse).
ServletResponse	getResponse() Получает ответ, который использовался, чтобы инициализировать этот AsyncContext, вызывая ServletRequest#startAsync() или ServletRequest#startAsync(ServletRequest, ServletResponse).
long	getTimeout() Получает тайм-аут (в миллисекундах) для этого AsyncContext.
boolean	hasOriginalRequestAndResponse() Проверки, если этот AsyncContext был инициализирован с исходным или обернутым в приложение запросом и объектами ответа.
void	setTimeout(long timeout) Устанавливает тайм-аут (в миллисекундах) для этого AsyncContext.
void	start(java.lang.Runnable run) Заставляет контейнер диспетчеризировать поток, возможно от управляемого пула потоков, выполнять указанный Runnable.

Полевая Деталь

ASYNC_REQUEST_URI

static final java.lang.String ASYNC_REQUEST_URI

Имя запроса приписывает, под которым исходный URI запроса делается доступным для цели a dispatch(String) или dispatch(ServletContext,String)

См. Также:

Постоянные Значения полей

ASYNC_CONTEXT_PATH

static final java.lang.String ASYNC_CONTEXT_PATH

Имя запроса приписывает, под которым исходный путь контекста делается доступным для цели a dispatch(String) или dispatch(ServletContext,String)

См. Также:

Постоянные Значения полей

ASYNC_PATH_INFO

static final java.lang.String ASYNC_PATH_INFO

Имя запроса приписывает, под которым исходная информация пути делается доступной для цели a dispatch(String) или dispatch(ServletContext,String)

См. Также:

Постоянные Значения полей

ASYNC_SERVLET_PATH

static final java.lang.String ASYNC_SERVLET_PATH

Имя запроса приписывает, под которым исходный путь сервлета делается доступным для цели a dispatch(String) или dispatch(ServletContext,String)

См. Также:

Постоянные Значения полей

ASYNC_QUERY_STRING

static final java.lang.String ASYNC_QUERY_STRING

Имя запроса приписывает, под которым исходная строка запроса делается доступной для цели a dispatch(String) или dispatch(ServletContext,String)

См. Также:

Постоянные Значения полей

Деталь метода

getRequest

ServletRequest getRequest()

Получает запрос, который использовался, чтобы инициализировать этот AsyncContext, вызывая ServletRequest#startAsync() или ServletRequest#startAsync(ServletRequest, ServletResponse).

Возвраты:

запрос, который использовался, чтобы инициализировать этот AsyncContext

getResponse

ServletResponse getResponse()

Получает ответ, который использовался, чтобы инициализировать этот AsyncContext, вызывая ServletRequest#startAsync() или ServletRequest#startAsync(ServletRequest, ServletResponse).

Возвраты:

ответ, который использовался, чтобы инициализировать этот AsyncContext

hasOriginalRequestAndResponse

boolean hasOriginalRequestAndResponse()

Проверки, если этот AsyncContext был инициализирован с исходным или обернутым в приложение запросом и объектами ответа.

Эта информация может использоваться фильтрами, вызванными в исходящем направлении, после того, как запрос был помещен в асинхронный режим, чтобы определить, должны ли любой запрос и/или обертки ответа, которые они добавили во время их входящего вызова, быть сохранены для продолжительности асинхронной работы, или могут быть выпущены.

Возвраты:

истина, если этот AsyncContext был инициализирован с исходным запросом и объектами ответа, вызывая ServletRequest#startAsync(), или если это было инициализировано, вызывая ServletRequest#startAsync(ServletRequest, ServletResponse), и ни параметры ServletRequest ни ServletResponse, которые переносят любые обеспеченные приложением обертки; ложь иначе

диспетчеризировать

void dispatch()

Диспетчеризирует запрос и объекты ответа этого AsyncContext к контейнеру сервлета.

Если асинхронный цикл был запущен с ServletRequest#startAsync(ServletRequest, ServletResponse), и запрос, который передают, является экземпляром HttpServletRequest, тогда диспетчеризирование к URI, возвращенному HttpServletRequest.getRequestURI(). Иначе, диспетчеризирование к URI запроса, когда это было последнее диспетчеризированный контейнером.

Следующая последовательность иллюстрирует, как это будет работать:

 // REQUEST dispatch to /url/A
 AsyncContext ac = request.startAsync();
 ...
 ac.dispatch(); // ASYNC dispatch to /url/A
 
 // FORWARD dispatch to /url/B
 getRequestDispatcher("/url/B").forward(request,response);
 // Start async operation from within the target of the FORWARD
 // dispatch
 ac = request.startAsync();
 ...
 ac.dispatch(); // ASYNC dispatch to /url/A
 
 // FORWARD dispatch to /url/B
 getRequestDispatcher("/url/B").forward(request,response);
 // Start async operation from within the target of the FORWARD
 // dispatch
 ac = request.startAsync(request,response);
 ...
 ac.dispatch(); // ASYNC dispatch to /url/B
 

Этот метод сразу возвращается после передачи запроса, и ответ возражает против контейнера управляемому потоку, на котором будет выполняться диспетчеризировать работа. Если этот метод вызывают прежде, чем инициируемые контейнером диспетчеризируют, который названный startAsync возвратил контейнеру, диспетчеризировать работа будет задержана, пока инициируемые контейнером не диспетчеризируют, возвратился к контейнеру.

Тип диспетчера запроса устанавливается в DispatcherType.ASYNC. В отличие от этого forward dispatches, буфер ответа и заголовки не будут сброшены, и законно диспетчеризировать, даже если ответ уже фиксировался.

Управление запросом и ответ делегируются к диспетчеризировать цели, и ответ будет закрыт, когда диспетчеризировать цель не завершила выполнение, если ServletRequest#startAsync() или ServletRequest#startAsync(ServletRequest, ServletResponse) вызываются.

Любые ошибки или исключения, которые могут произойти во время выполнения этого метода, должны быть пойманы и обработаны контейнером, следующим образом:

1. Вызовите в их onError метод, все AsyncListener экземпляры, зарегистрированные в ServletRequest, для которого этот AsyncContext создавался, и делает пойманный Throwable доступным через AsyncEvent#getThrowable.
2. Если ни одного из слушателей не вызывают complete() или любой из dispatch() методы, выполните ошибку, диспетчеризируют с кодом состояния, равным HttpServletResponse.SC_INTERNAL_SERVER_ERROR, и делают вышеупомянутый Throwable доступным как значение атрибута запроса RequestDispatcher.ERROR_EXCEPTION.
3. Если никакая ошибочная страница соответствия не была найдена, или ошибочная страница не вызывала complete() или любой из dispatch() методы, вызвать complete().

Может быть самое большее одно асинхронное, диспетчеризируют работу на асинхронный цикл, который запускается звонком в один из ServletRequest#startAsync методы. Любая попытка выполнить дополнительное асинхронное диспетчеризирует работу в пределах того же самого асинхронного цикла, приведет к IllegalStateException. Если startAsync впоследствии вызывают по диспетчеризированному запросу, то какое-либо диспетчеризирование или complete() методы можно вызвать.

Броски:

IllegalStateException - если один из диспетчеризировать методов вызвали, и startAsync метод не вызвали во время получающегося, диспетчеризируют, или если complete() был вызван

См. Также:

ServletRequest#getDispatcherType

диспетчеризировать

void dispatch(java.lang.String path)

Диспетчеризирует запрос и объекты ответа этого AsyncContext к данному path.

Параметр path интерпретируется таким же образом как в ServletRequest#getRequestDispatcher(String), в рамках ServletContext от которого был инициализирован этот AsyncContext.

Связанные методы запроса всего пути запроса должны отразить диспетчеризировать цель, в то время как исходный URI запроса, путь контекста, информация пути, путь сервлета, и строка запроса могут быть восстановлены с ASYNC_REQUEST_URI, ASYNC_CONTEXT_PATH, ASYNC_PATH_INFO, ASYNC_SERVLET_PATH, и ASYNC_QUERY_STRING атрибуты запроса. Эти атрибуты будут всегда отражать, что исходные элементы пути, даже под повторным диспетчеризирует.

Может быть самое большее одно асинхронное, диспетчеризируют работу на асинхронный цикл, который запускается звонком в один из ServletRequest#startAsync методы. Любая попытка выполнить дополнительное асинхронное диспетчеризирует работу в пределах того же самого асинхронного цикла, приведет к IllegalStateException. Если startAsync впоследствии вызывают по диспетчеризированному запросу, то какое-либо диспетчеризирование или complete() методы можно вызвать.

См. dispatch() для дополнительных деталей, включая обработку ошибок.

Параметры:

path - путь диспетчеризировать цели, определяющей контекст к ServletContext, от которого был инициализирован этот AsyncContext

Броски:

IllegalStateException - если один из диспетчеризировать методов вызвали, и startAsync метод не вызвали во время получающегося, диспетчеризируют, или если complete() был вызван

См. Также:

ServletRequest#getDispatcherType

диспетчеризировать

void dispatch(ServletContext context,
              java.lang.String path)

Диспетчеризирует запрос и объекты ответа этого AsyncContext к данному path, определяющему контекст к данному context.

Параметр path интерпретируется таким же образом как в ServletRequest#getRequestDispatcher(String), за исключением того, что это является определяющим контекст к данному context.

Связанные методы запроса всего пути запроса должны отразить диспетчеризировать цель, в то время как исходный URI запроса, путь контекста, информация пути, путь сервлета, и строка запроса могут быть восстановлены с ASYNC_REQUEST_URI, ASYNC_CONTEXT_PATH, ASYNC_PATH_INFO, ASYNC_SERVLET_PATH, и ASYNC_QUERY_STRING атрибуты запроса. Эти атрибуты будут всегда отражать, что исходные элементы пути, даже под повторным диспетчеризирует.

Может быть самое большее одно асинхронное, диспетчеризируют работу на асинхронный цикл, который запускается звонком в один из ServletRequest#startAsync методы. Любая попытка выполнить дополнительное асинхронное диспетчеризирует работу в пределах того же самого асинхронного цикла, приведет к IllegalStateException. Если startAsync впоследствии вызывают по диспетчеризированному запросу, то какое-либо диспетчеризирование или complete() методы можно вызвать.

См. dispatch() для дополнительных деталей, включая обработку ошибок.

Параметры:

context - ServletContext диспетчеризировать цели

path - путь диспетчеризировать цели, определяющей контекст к данному ServletContext

Броски:

IllegalStateException - если один из диспетчеризировать методов вызвали, и startAsync метод не вызвали во время получающегося, диспетчеризируют, или если complete() был вызван

См. Также:

ServletRequest#getDispatcherType

полный

void complete()

Завершает асинхронную работу, которая была запущена по запросу, который привык к initialze этот AsyncContext, закрывая ответ, который использовался, чтобы инициализировать этот AsyncContext.

Любые слушатели типа AsyncListener это было зарегистрировано в ServletRequest, для которого создавался этот AsyncContext, будет вызван в их onComplete метод.

Законно вызвать этот метод любое время после звонка ServletRequest#startAsync() или ServletRequest#startAsync(ServletRequest, ServletResponse), и перед звонком в один из методов dispatch этого class. Если этот метод вызывают прежде, чем инициируемые контейнером диспетчеризируют, который названный startAsync возвратил контейнеру, то вызов не будет вступать в силу (и любые вызовы AsyncListener#onComplete(AsyncEvent) будет задержан), пока инициируемые контейнером не диспетчеризируют, возвратился к контейнеру.

запустить

void start(java.lang.Runnable run)

Заставляет контейнер диспетчеризировать поток, возможно от управляемого пула потоков, выполнять указанный Runnable. Контейнер может распространить соответствующую контекстную информацию к Runnable.

Параметры:

run - асинхронный обработчик

addListener

void addListener(AsyncListener listener)

Регистрирует данный AsyncListener с новым асинхронным циклом, который был запущен звонком в один из ServletRequest#startAsync методы.

Данный AsyncListener получит AsyncEvent когда асинхронный цикл завершается успешно, времена, или приводит к ошибке.

Экземпляры AsyncListener будут уведомлены в порядке, в котором они были добавлены.

Параметры:

listener - AsyncListener, который будет зарегистрирован

Броски:

IllegalStateException - если этот метод вызывают после того, как инициируемые контейнером диспетчеризируют, во время который ServletRequest#startAsync методы вызвали, возвратился к контейнеру

addListener

void addListener(AsyncListener listener,
                 ServletRequest servletRequest,
                 ServletResponse servletResponse)

Регистрирует данный AsyncListener с новым асинхронным циклом, который был запущен звонком в один из ServletRequest#startAsync методы.

Данный AsyncListener получит AsyncEvent когда асинхронный цикл завершается успешно, времена, или приводит к ошибке.

Экземпляры AsyncListener будут уведомлены в порядке, в котором они были добавлены.

Данные объекты ServletRequest и ServletResponse будут сделаны доступными для данного AsyncListener через getSuppliedRequest и getSuppliedResponse методы, соответственно, AsyncEvent поставленный этому. Эти объекты не должны быть считаны из или записаны, соответственно, в то время, когда AsyncEvent поставляют, потому что дополнительное обертывание, возможно, произошло, так как данный AsyncListener был зарегистрирован, но может использоваться, чтобы высвободить любые средства, связанные с ними.

Параметры:

listener - AsyncListener, который будет зарегистрирован

servletRequest - ServletRequest, который будет включен в AsyncEvent

servletResponse - ServletResponse, который будет включен в AsyncEvent

Броски:

IllegalStateException - если этот метод вызывают после того, как инициируемые контейнером диспетчеризируют, во время который ServletRequest#startAsync методы вызвали, возвратился к контейнеру

createListener

<T extends AsyncListener> T createListener(java.lang.Class<T> clazz)
                                       throws ServletException

Инстанцирует данного AsyncListener class.

Возвращенный экземпляр AsyncListener может быть далее настроен прежде, чем он будет зарегистрирован в этом AsyncContext через звонок в один из addListener методы.

Данный class AsyncListener должен определить нулевого конструктора параметра, который используется, чтобы инстанцировать его.

Этот метод поддерживает инжекцию ресурса, если данный clazz представляет Управляемый Боб. См. платформу EE Java и JSR 299 спецификаций для дополнительных деталей об Управляемых Бобах и инжекции ресурса.

Этот метод поддерживает любые аннотации, применимые к AsyncListener.

Параметры:

clazz - AsyncListener class, чтобы инстанцировать

Возвраты:

новый экземпляр AsyncListener

Броски:

ServletException - если данный clazz не в состоянии быть инстанцированным

setTimeout

void setTimeout(long timeout)

Устанавливает тайм-аут (в миллисекундах) для этого AsyncContext.

Тайм-аут применяется к этому AsyncContext, как только инициируемые контейнером диспетчеризируют во время который ServletRequest#startAsync методы вызвали, возвратился к контейнеру.

Тайм-аут истечет если ни один complete() метод, ни любой из диспетчеризировать методов вызывают. Значение тайм-аута нуля или меньше не указывает ни на какой тайм-аут.

Если setTimeout(long) не вызывается, тогда тайм-аут значения по умолчанию контейнера, который доступен через звонок getTimeout(), будет применяться.

Параметры:

timeout - тайм-аут в миллисекундах

Броски:

IllegalStateException - если этот метод вызывают после того, как инициируемые контейнером диспетчеризируют, во время который ServletRequest#startAsync методы вызвали, возвратился к контейнеру

getTimeout

long getTimeout()

Получает тайм-аут (в миллисекундах) для этого AsyncContext.

Этот метод возвращает тайм-аут значения по умолчанию контейнера для асинхронных операций, или значение тайм-аута, которое передают к новому вызову setTimeout(long).

Значение тайм-аута нуля или меньше не указывает ни на какой тайм-аут.

Возвраты:

тайм-аут в миллисекундах