Package org.frankframework.http.rest

Class ApiListener

java.lang.Object
org.frankframework.http.PushingListenerAdapter
org.frankframework.http.rest.ApiListener
All Implemented Interfaces:
FrankElement, HasApplicationContext, HasName, HasPhysicalDestination, IConfigurable, IListener<Message>, IPushingListener<Message>, IScopeProvider, NameAware, 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

  • Field Details

    • RESERVED_NAMES

      public static final Set<String> RESERVED_NAMES
      These are names that are never allowed as HTTP parameters, because the Frank!Framework sets these names as session variables.

  • 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
      Overrides:
      configure in class PushingListenerAdapter
      Throws:
      ConfigurationException - in case it was not able to configure the component.

    • start

      public void start()
      Description copied from interface: IListener
      Prepares the listener for receiving messages. start() 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

    • isParameterAllowed

      public boolean isParameterAllowed(@Nonnull String parameterName)

    • 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.
      Pattern variables like {something} in this example are added to the PipeLineSession with their actual value in the request URI.
      Pattern variables are not allowed to have the same name as any of the RESERVED_NAMES.

    • 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.
      The multipartBodyName or the names of any other multipart fields may not be one of the RESERVED_NAMES.
      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

    • setAllowedParameters

      public void setAllowedParameters(@Nullable String paramWhitelist)
      Whitelist of request parameters (Query and POST Parameters) that are allowed to be copied into the session.
      Entered as a comma-separated value.
      If the list contains any names that are in RESERVED_NAMES, these will be removed from the list.
      If left empty, then all HTTP parameters are copied into the session, which can pose a security risk and is therefore discouraged. The risk is that parameters could be sent, that overwrite system session variables.
      This only works as a backwards-compatibility feature and can be switched off setting setAllowAllParams(boolean) to false.
      Parameters:
      paramWhitelist - Comma-separated list of allowed HTTP parameters.

    • setAllowAllParams

      public void setAllowAllParams(boolean allowAllParams)
      For backwards compatibility with configurations that have not yet been updated, by default all parameters are allowed until removal of this flag. Copying all POST and query parameters to the session is considered a security risk, so this should not be left enabled.
      Even so, names listed in RESERVED_NAMES will never be copied from the HTTP parameters to the session.
      When setting setAllowedParameters(String), this value is ignored. This value is only used when the allowed parameter list has not been set, or set empty.
      For backwards compatibility, this is true by default.
      Default value
      true

    • isAllowAllParams

      public boolean isAllowAllParams()

    • 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()

    • getAllowedParameterSet

      @Nonnull public Set<String> getAllowedParameterSet()

    • getAllowAllParams

      public Boolean getAllowAllParams()

    • 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()