com.eclipsesource.restfuse.annotation.Callback Maven / Gradle / Ivy
Show all versions of com.eclipsesource.restfuse Show documentation
/*******************************************************************************
* Copyright (c) 2011 EclipseSource and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Holger Staudacher - initial API and implementation
******************************************************************************/
package com.eclipsesource.restfuse.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import com.eclipsesource.restfuse.CallbackResource;
import com.eclipsesource.restfuse.DefaultCallbackResource;
import com.eclipsesource.restfuse.Destination;
/**
* The Callback can be used for asynchronous HTTP tests that need a callback.
* This means when the tested service needs to send something back within a separate request. At
* this time the client needs to act as a service to accept the incoming request. See
* this wiki for more information
* about webhooks.
*
* Please note, that the Callback annotation only works in combination with the
* {@link HttpTest} annotation. This means it can't be used standalone and it
* has the same prerequisites as the {@link HttpTest}.
*
* Once a request has finished on an http test method and the method has a Callback
* annotation attached, a sever will be started before the test code will be executed. On this
* server a servlet will be registered on the port specified in the port attribute
* using the path specified in the path attribute. After the test code finished the
* server waits until the timeout has reached or the callback was called. If the
* callback was not done than the test method fails. In any case the server shuts itself down after
* the test method execution.
*
* Of course you want to test something when the callback arrives. Therefore you need to register
* a resource using the resource attribute. The value of this attributes has to be a
* subclass of {@link CallbackResource}. For convenience you can also subclass the
* {@link DefaultCallbackResource} which implements all methods and returns a default
* response instead of sub classing the {@link CallbackResource} directly.
*
* A simple callback looks like this:
*
* @RunWith( HttpJUnitRunner.class )
* public class Example {
*
* @Rule
* public Destination destination = new Destination( "http://localhost" );
*
* @Context
* private Response response;
*
* private class TestCallbackResource extends DefaultCallbackResource {
*
* @Override
* public Response post( Request request ) {
* assertNotNull( request.getHeaders().get( "some header" ).get( 0 ) );
* return super.post( request );
* }
* }
*
* @HttpTest( method = Method.GET, path = "/test" )
* @Callback( port = 9090, path = "/callback", resource = TestCallbackResource.class, timeout = 10000 )
* public void testMethod() {
* com.eclipsesource.restfuse.Assert.assertAccepted( response );
* }
* }
*
*
*
* @see CallbackResource
* @see DefaultCallbackResource
* @see HttpTest
* @see Destination
*/
@Retention( RetentionPolicy.RUNTIME )
@Target( { ElementType.METHOD } )
public @interface Callback {
/**
* The port attribute specifies the port on which the callback will be reachable
* during the test method execution.
*/
int port();
/**
* The path attribute specifies the path on which the callback will be reachable
* during the test method execution.
*/
String path();
/**
* The resource attribute specifies the class that will be instantiated and
* handles the incoming requests from a callback. Instead of sub classing
* {@link CallbackResource} directly you can also subclass
* {@link DefaultCallbackResource} which implements all methods and returns a
* default response.
*
* @see CallbackResource
* @see DefaultCallbackResource
*/
Class resource();
/**
* The timeout attribute specifies the milliseconds of the callback timeout. This
* means, that if the callback was not called within the given time frame, the test method will
* fail.
*/
int timeout();
}