Package org.frankframework.http.rest

Class ApiListener

java.lang.Object
org.frankframework.http.PushingListenerAdapter
org.frankframework.http.rest.ApiListener
All Implemented Interfaces:
HasPhysicalDestination, IConfigurable, IConfigurationAware, IListener<Message>, INamedObject, IPushingListener<Message>, IScopeProvider, ReceiverAware<Message>, ServiceClient, org.springframework.beans.factory.Aware, org.springframework.context.ApplicationContextAware
public class ApiListener extends PushingListenerAdapter implements HasPhysicalDestination, ReceiverAware<Message>
Listener that allows a Receiver to receive messages as a REST webservice. Prepends the configured URI pattern with api/. The structure of REST messages is described by OpenAPI specifications. The Frank!Framework generates an OpenAPI specification for each ApiListener and for all ApiListeners in all configurations combined. You can find them in the Frank!Console under main menu item Webservices, heading Available ApiListeners.

The generated OpenAPI specifications have servers and paths objects and therefore they document the full URLs of the provided services.

It is possible to automatically generate eTags over the listener result. This can be controlled by globally setting the property api.etag.enabled or by setting the attribute updateEtag="true". When enabled the listener will respond to the If-Match, If-None-Match headers and may return status code 304.

In order to enable eTags for multiple nodes you must configure Memcached to store the eTags. The following properties will need to be set:

  • etag.cache.server=ip or hostname:port
  • etag.cache.type=memcached
In case authentication, is required the following application properties can be used:
  • etag.cache.username
  • etag.cache.password
  • etag.cache.authalias
Author:
Niels Meijer

  • Constructor Details

    • ApiListener

      public ApiListener()

  • Method Details

    • configure

      public void configure() throws ConfigurationException
      initialize listener and register this to the JNDI
      Specified by:
      configure in interface IConfigurable
      Specified by:
      configure in interface IListener<Message>
      Overrides:
      configure in class PushingListenerAdapter
      Throws:
      ConfigurationException

    • start

      public void start()
      Description copied from interface: IListener
      Prepares the listener for receiving messages. open() is called once each time the listener is started.
      Specified by:
      start in interface IListener<Message>
      Overrides:
      start in class PushingListenerAdapter

    • stop

      public void stop()
      Description copied from interface: IListener
      Close all resources used for listening. Called once each time the listener is stopped.
      Specified by:
      stop in interface IListener<Message>
      Overrides:
      stop in class PushingListenerAdapter

    • getCleanPattern

      public String getCleanPattern()
      returns the clear pattern, replaces everything between {} to *
      Returns:
      null if no pattern is found

    • isConsumable

      public boolean isConsumable(@Nullable String contentType)
      Match request 'Content-Type' (eg. on POST) to consumes enum to see if the listener accepts the message

    • accepts

      public boolean accepts(@Nullable String acceptHeader)
      Match request 'Accept' header to produces enum to see if the client accepts the message

    • setMethod

      public void setMethod(ApiListener.HttpMethod method)
      HTTP method to listen to
      Default value
      GET

    • getAllMethods

      public List<ApiListener.HttpMethod> getAllMethods()

    • setMethods

      public void setMethods(ApiListener.HttpMethod... methods)
      HTTP method(s) to listen to. Inside XML Configurations: for multiple values, use a comma as separator.
      Default value
      GET

    • setUriPattern

      public void setUriPattern(String uriPattern)
      URI pattern to register this listener on, eq. /my-listener/{something}/here

    • setConsumes

      public void setConsumes(@Nonnull MediaTypes value)
      The required contentType on requests, if it doesn't match a 415 status (Unsupported Media Type) is returned.
      Default value
      ANY

    • setProduces

      public void setProduces(@Nonnull MediaTypes value)
      The specified contentType on response. When ANY the response will determine the content-type when it's known and will never calculate it. If no match is found */* will be used. When DETECT the framework attempts to detect the MimeType (as well as charset) when not known.
      Default value
      ANY

    • setCharacterEncoding

      public void setCharacterEncoding(String charset)
      The specified character encoding on the response contentType header. NULL or empty values will be ignored.
      Default value
      UTF-8

    • setUpdateEtag

      public void setUpdateEtag(boolean updateEtag)
      Automatically generate and validate etags
      Default value
      false, can be changed by setting the property api.etag.enabled.

    • setAuthenticationMethod

      public void setAuthenticationMethod(ApiListener.AuthenticationMethods authenticationMethod)
      Enables security for this listener. If you wish to use the application servers authorization roles [AUTHROLE], you need to enable them globally for all ApiListeners with the servlet.ApiListenerServlet.securityRoles=IbisTester,IbisWebService property
      Default value
      NONE

    • setAuthenticationRoles

      public void setAuthenticationRoles(String authRoles)
      Only active when AuthenticationMethod=AUTHROLE. Comma separated list of authorization roles which are granted for this service, eq. IbisTester,IbisObserver

    • getAuthenticationRoleList

      public List<String> getAuthenticationRoleList()

    • setMultipartBodyName

      public void setMultipartBodyName(String multipartBodyName)
      Specify the form-part you wish to enter the pipeline
      Default value
      name of the first form-part

    • getMultipartBodyName

      public String getMultipartBodyName()

    • setMessageIdHeader

      @Default("Message-Id") public void setMessageIdHeader(String messageIdHeader)
      Name of the header which contains the Message-Id.

    • setCorrelationIdHeader

      @Default("Correlation-Id") public void setCorrelationIdHeader(String correlationIdHeader)
      Name of the header which contains the Correlation-Id.

    • setOperationId

      public void setOperationId(String operationId)
      Unique string used to identify the operation. The id MUST be unique among all operations described in the OpenApi schema.

    • setHeaderParams

      public void setHeaderParams(String headerParams)
      Comma separated list of parameters passed as http header. Parameters will be stored in 'headers' sessionkey.

    • setContentDispositionHeaderSessionKey

      public void setContentDispositionHeaderSessionKey(String key)
      Session key that provides the Content-Disposition header in the response

    • setRequiredIssuer

      public void setRequiredIssuer(String issuer)
      Issuer to validate JWT

    • setJwksURL

      public void setJwksURL(String string)
      Keysource URL to validate JWT

    • setJwtHeader

      public void setJwtHeader(String string)
      Header to extract JWT from
      Default value
      Authorization

    • setRequiredClaims

      public void setRequiredClaims(String string)
      Comma separated list of required claims

    • setExactMatchClaims

      public void setExactMatchClaims(String string)
      Comma separated key value pairs to exactly match with JWT payload. e.g. sub=UnitTest, aud=test

    • setAnyMatchClaims

      public void setAnyMatchClaims(String string)
      Comma separated key value pairs to one-of match with JWT payload. e.g. appid=a,appid=b

    • setRoleClaim

      public void setRoleClaim(String roleClaim)
      Claim name which specifies the role (maps to IsUserInRolePipe)

    • setPrincipalNameClaim

      public void setPrincipalNameClaim(String principalNameClaim)
      Claim name which specifies the principal name (maps to GetPrincipalPipe)

    • setResponseType

      public void setResponseType(HttpEntityType responseType)
      Optional configuration setting to have more control over how to send the response. Set this to return data as Multipart formdata or MTOM. See HttpEntityType for all supported values and how to use them.
      Default value
      HttpEntityType.BINARY.

    • setResponseMultipartXmlSessionKey

      public void setResponseMultipartXmlSessionKey(String responseMultipartXmlSessionKey)
      If response is sent as Multipart (HttpEntityType.FORMDATA or HttpEntityType.MTOM) an optional session key can describe the Multipart contents in XML. See HttpSender.setMultipartXmlSessionKey(String) for details on the XML format specification.

    • setResponseFirstBodyPartName

      public void setResponseFirstBodyPartName(String responseFirstBodyPartName)
      If response is sent as Multipart (HttpEntityType.FORMDATA or HttpEntityType.MTOM), when this option is set the pipeline result message will be prepended as first Multipart Bodypart with this name.

    • setResponseMtomContentTransferEncoding

      public void setResponseMtomContentTransferEncoding(String responseMtomContentTransferEncoding)
      If the response is sent as HttpEntityType.MTOM, optionally specify the transfer-encoding of the first part.

    • toString

      public String toString()
      Overrides:
      toString in class PushingListenerAdapter

    • isValidUriPattern

      public static boolean isValidUriPattern(String uriPattern)

    • getDomain

      public String getDomain()
      Specified by:
      getDomain in interface HasPhysicalDestination

    • getUriPattern

      public String getUriPattern()

    • isUpdateEtag

      public boolean isUpdateEtag()

    • getOperationId

      public String getOperationId()

    • getAuthenticationMethod

      public ApiListener.AuthenticationMethods getAuthenticationMethod()

    • getConsumes

      public MediaTypes getConsumes()

    • getProduces

      public MediaTypes getProduces()

    • getContentType

      public org.springframework.util.MimeType getContentType()

    • getReceiver

      public Receiver<Message> getReceiver()
      Specified by:
      getReceiver in interface ReceiverAware<Message>

    • setReceiver

      public void setReceiver(Receiver<Message> receiver)
      Specified by:
      setReceiver in interface ReceiverAware<Message>

    • getMessageIdHeader

      public String getMessageIdHeader()

    • getCorrelationIdHeader

      public String getCorrelationIdHeader()

    • getHeaderParams

      public String getHeaderParams()

    • getContentDispositionHeaderSessionKey

      public String getContentDispositionHeaderSessionKey()

    • getCharset

      public String getCharset()

    • getRequiredIssuer

      public String getRequiredIssuer()

    • getJwksUrl

      public String getJwksUrl()

    • getJwtHeader

      public String getJwtHeader()

    • getRequiredClaims

      public String getRequiredClaims()

    • getExactMatchClaims

      public String getExactMatchClaims()

    • getAnyMatchClaims

      public String getAnyMatchClaims()

    • getRoleClaim

      public String getRoleClaim()

    • getPrincipalNameClaim

      public String getPrincipalNameClaim()

    • getPhysicalDestinationName

      public String getPhysicalDestinationName()
      Specified by:
      getPhysicalDestinationName in interface HasPhysicalDestination

    • getJwtValidator

      public JwtValidator<com.nimbusds.jose.proc.SecurityContext> getJwtValidator()

    • setServletManager

      public void setServletManager(ServletManager servletManager)

    • getResponseType

      public HttpEntityType getResponseType()

    • getResponseMultipartXmlSessionKey

      public String getResponseMultipartXmlSessionKey()

    • getResponseFirstBodyPartName

      public String getResponseFirstBodyPartName()

    • getResponseMtomContentTransferEncoding

      public String getResponseMtomContentTransferEncoding()

    • getResponseEntityBuilder

      public HttpEntityFactory getResponseEntityBuilder()