Package com.linecorp.armeria.common.logging

Interface RequestLogAccess

All Known Subinterfaces:

RequestLog, RequestLogBuilder, RequestOnlyLog

public interface RequestLogAccess

Provides the access to a RequestLog or RequestOnlyLog, while ensuring the interested RequestLogPropertys are available.

The properties provided by RequestLog are not always fully available. Use the following methods to access the properties safely:

• isComplete() or whenComplete() to check if or to get notified when all request and response properties are available.
• isRequestComplete() or whenRequestComplete() to check if or to get notified when all request properties are available.
• isAvailable(RequestLogProperty), isAvailable(RequestLogProperty...), isAvailable(Iterable), whenAvailable(RequestLogProperty), whenAvailable(RequestLogProperty...) or whenAvailable(Iterable) to check if or to get notified when a certain set of properties are available.

If you are sure that certain properties are available, you can convert a RequestLogAccess into a RequestLog or RequestOnlyLog by using the "ensure*()" methods, such as ensureComplete() and ensureRequestComplete().

Method Summary

Modifier and Type	Method	Description
int	availabilityStamp()	Returns an int representation of the currently available properties of this RequestLog.
List<RequestLogAccess>	children()	Returns the list of RequestLogAccesses that provide access to the child RequestLogs, ordered by the time they were added.
RequestContext	context()	Returns the RequestContext associated with the Request being handled.
RequestLog	ensureAvailable(RequestLogProperty property)	Returns the RequestLog that is guaranteed to have the specified RequestLogProperty.
RequestLog	ensureAvailable(RequestLogProperty... properties)	Returns the RequestLog that is guaranteed to have all the specified RequestLogPropertys.
RequestLog	ensureAvailable(Iterable<RequestLogProperty> properties)	Returns the RequestLog that is guaranteed to have all the specified RequestLogPropertys.
RequestLog	ensureComplete()	Returns the RequestLog that is guaranteed to have all properties, for both request and response side.
RequestOnlyLog	ensureRequestComplete()	Returns the RequestLog that is guaranteed to have all request-side properties.
@Nullable RequestLog	getIfAvailable(RequestLogProperty... properties)	Returns RequestLog if all of the specified RequestLogPropertys are available.
@Nullable RequestLog	getIfAvailable(Iterable<RequestLogProperty> properties)	Returns RequestLog if all of the specified RequestLogPropertys are available.
boolean	isAvailable(RequestLogProperty property)	Returns true if the specified RequestLogProperty is available.
boolean	isAvailable(RequestLogProperty... properties)	Returns true if all of the specified RequestLogPropertys are available.
boolean	isAvailable(Iterable<RequestLogProperty> properties)	Returns true if all of the specified RequestLogPropertys are available.
boolean	isComplete()	Returns true if the Request has been processed completely and thus all properties of the RequestLog have been collected.
boolean	isRequestComplete()	Returns true if the Request has been consumed completely and thus all properties of the RequestOnlyLog have been collected.
@Nullable RequestLogAccess	parent()	Returns the RequestLogAccess that provides access to the parent RequestLog.
RequestLog	partial()	Returns the RequestLog for the Request, where all properties may not be available yet.
CompletableFuture<RequestLog>	whenAvailable(RequestLogProperty property)	Returns a CompletableFuture which will be completed when the specified RequestLogProperty is collected.
CompletableFuture<RequestLog>	whenAvailable(RequestLogProperty... properties)	Returns a CompletableFuture which will be completed when all the specified RequestLogPropertys are collected.
CompletableFuture<RequestLog>	whenAvailable(Iterable<RequestLogProperty> properties)	Returns a CompletableFuture which will be completed when all the specified RequestLogPropertys are collected.
CompletableFuture<RequestLog>	whenComplete()	Returns a CompletableFuture which will be completed when the Request has been processed completely and thus all properties of the RequestLog have been collected.
CompletableFuture<RequestOnlyLog>	whenRequestComplete()	Returns a CompletableFuture which will be completed when the Request has been consumed completely and thus all properties of the RequestOnlyLog have been collected.

Method Details

isComplete

boolean isComplete()

Returns true if the Request has been processed completely and thus all properties of the RequestLog have been collected.

isRequestComplete

boolean isRequestComplete()

Returns true if the Request has been consumed completely and thus all properties of the RequestOnlyLog have been collected.

isAvailable

boolean isAvailable(RequestLogProperty property)

Returns true if the specified RequestLogProperty is available.

isAvailable

boolean isAvailable(RequestLogProperty... properties)

Returns true if all of the specified RequestLogPropertys are available.

Throws:

IllegalArgumentException - if properties is empty.

isAvailable

boolean isAvailable(Iterable<RequestLogProperty> properties)

Returns true if all of the specified RequestLogPropertys are available.

Throws:

IllegalArgumentException - if properties is empty.

getIfAvailable

@UnstableApi
@Nullable
@Nullable RequestLog getIfAvailable(RequestLogProperty... properties)

Returns RequestLog if all of the specified RequestLogPropertys are available.

getIfAvailable

@UnstableApi
@Nullable
@Nullable RequestLog getIfAvailable(Iterable<RequestLogProperty> properties)

Returns RequestLog if all of the specified RequestLogPropertys are available.

whenComplete

CompletableFuture<RequestLog> whenComplete()

Returns a CompletableFuture which will be completed when the Request has been processed completely and thus all properties of the RequestLog have been collected. The returned CompletableFuture is never completed exceptionally.

 logAccess.whenComplete().thenAccept(log -> {
     HttpStatus status = log.responseHeaders().status();
     if (status == HttpStatus.OK) {
         ...
     }
 });
 

whenRequestComplete

CompletableFuture<RequestOnlyLog> whenRequestComplete()

Returns a CompletableFuture which will be completed when the Request has been consumed completely and thus all properties of the RequestOnlyLog have been collected. The returned CompletableFuture is never completed exceptionally.

 logAccess.whenRequestComplete().thenAccept(log -> {
     SerializationFormat serFmt = log.scheme().serializationFormat();
     if (serFmt == ThriftSerializationFormats.BINARY) {
         ...
     }
 });
 

whenAvailable

CompletableFuture<RequestLog> whenAvailable(RequestLogProperty property)

Returns a CompletableFuture which will be completed when the specified RequestLogProperty is collected. The returned CompletableFuture is never completed exceptionally. Note that the completion of the returned CompletableFuture guarantees only the availability of the specified property, which means any attempt to access other properties than specified may trigger a RequestLogAvailabilityException. If in doubt, use whenComplete() or whenRequestComplete().

 logAccess.whenAvailable(RequestLogProperty.REQUEST_HEADERS)
          .thenAccept(log -> {
              RequestHeaders headers = log.requestHeaders();
              if (headers.path().startsWith("/foo/")) {
                  ...
              }
          });
 

whenAvailable

CompletableFuture<RequestLog> whenAvailable(RequestLogProperty... properties)

Returns a CompletableFuture which will be completed when all the specified RequestLogPropertys are collected. The returned CompletableFuture is never completed exceptionally. Note that the completion of the returned CompletableFuture guarantees only the availability of the specified properties, which means any attempt to access other properties than specified may trigger a RequestLogAvailabilityException. If in doubt, use whenComplete() or whenRequestComplete().

 logAccess.whenAvailable(RequestLogProperty.REQUEST_HEADERS,
                         RequestLogProperty.RESPONSE_HEADERS)
          .thenAccept(log -> {
              RequestHeaders reqHeaders = log.requestHeaders();
              ResponseHeaders resHeaders = log.responseHeaders();
              if (reqHeaders.path().startsWith("/foo/") &&
                  resHeaders.status() == HttpStatus.OK) {
                  ...
              }
          });
 

Throws:

IllegalArgumentException - if properties is empty.

whenAvailable

CompletableFuture<RequestLog> whenAvailable(Iterable<RequestLogProperty> properties)

Returns a CompletableFuture which will be completed when all the specified RequestLogPropertys are collected. The returned CompletableFuture is never completed exceptionally. Note that the completion of the returned CompletableFuture guarantees only the availability of the specified properties, which means any attempt to access other properties than specified may trigger a RequestLogAvailabilityException. If in doubt, use whenComplete() or whenRequestComplete().

 logAccess.whenAvailable(Lists.of(RequestLogProperty.REQUEST_HEADERS,
                                  RequestLogProperty.RESPONSE_HEADERS))
          .thenAccept(log -> {
              RequestHeaders reqHeaders = log.requestHeaders();
              ResponseHeaders resHeaders = log.responseHeaders();
              if (reqHeaders.path().startsWith("/foo/") &&
                  resHeaders.status() == HttpStatus.OK) {
                  ...
              }
          });
 

Throws:

IllegalArgumentException - if properties is empty.

ensureComplete

RequestLog ensureComplete()

Returns the RequestLog that is guaranteed to have all properties, for both request and response side.

Throws:

RequestLogAvailabilityException - if the Request was not fully processed yet.

ensureRequestComplete

RequestOnlyLog ensureRequestComplete()

Returns the RequestLog that is guaranteed to have all request-side properties.

Throws:

RequestLogAvailabilityException - if the Request was not fully consumed yet.

ensureAvailable

RequestLog ensureAvailable(RequestLogProperty property)

Returns the RequestLog that is guaranteed to have the specified RequestLogProperty.

Throws:

RequestLogAvailabilityException - if the specified RequestLogProperty is not available yet.

ensureAvailable

RequestLog ensureAvailable(RequestLogProperty... properties)

Returns the RequestLog that is guaranteed to have all the specified RequestLogPropertys.

Throws:

RequestLogAvailabilityException - if any of the specified RequestLogPropertys are not available yet.

IllegalArgumentException - if properties is empty.

ensureAvailable

RequestLog ensureAvailable(Iterable<RequestLogProperty> properties)

Returns the RequestLog that is guaranteed to have all the specified RequestLogPropertys.

Throws:

RequestLogAvailabilityException - if any of the specified RequestLogPropertys are not available yet.

IllegalArgumentException - if properties is empty.

partial

RequestLog partial()

Returns the RequestLog for the Request, where all properties may not be available yet. Note that this method is potentially unsafe; an attempt to access an unavailable property will trigger a RequestLogAvailabilityException. If in doubt, use whenComplete() or whenRequestComplete(). Always consider guarding the property access with isAvailable(RequestLogProperty) when you have to use this method:

 RequestLogAccess logAccess = ...;
 if (logAccess.isAvailable(RequestLogProperty.REQUEST_HEADERS)) {
     RequestHeaders headers = logAccess.partial().requestHeaders();
     ...
 }
 

availabilityStamp

int availabilityStamp()

Returns an int representation of the currently available properties of this RequestLog. This can be useful when needing to quickly compare the availability of the RequestLog during the processing of the request. Use isAvailable(RequestLogProperty) to actually check availability.

context

RequestContext context()

Returns the RequestContext associated with the Request being handled.

This method always returns non-null regardless of what properties are currently available.

parent

@Nullable
@Nullable RequestLogAccess parent()

Returns the RequestLogAccess that provides access to the parent RequestLog. null is returned if the RequestLog was not added as a child log.

See Also:

• RequestLogBuilder.addChild(RequestLogAccess)

children

List<RequestLogAccess> children()

Returns the list of RequestLogAccesses that provide access to the child RequestLogs, ordered by the time they were added.