org.apache.flink.runtime.rest.versioning.RestAPIVersion Java Examples

@Test
public void testInvalidVersionRejection() throws Exception {
	try (final RestClient restClient = new RestClient(RestClientConfiguration.fromConfiguration(new Configuration()), Executors.directExecutor())) {
		CompletableFuture<EmptyResponseBody> invalidVersionResponse = restClient.sendRequest(
			unroutableIp,
			80,
			new TestMessageHeaders(),
			EmptyMessageParameters.getInstance(),
			EmptyRequestBody.getInstance(),
			Collections.emptyList(),
			RestAPIVersion.V0
		);
		Assert.fail("The request should have been rejected due to a version mismatch.");
	} catch (IllegalArgumentException e) {
		// expected
	}
}
 

@Test
public void testVersioning() throws Exception {
	CompletableFuture<EmptyResponseBody> unspecifiedVersionResponse = restClient.sendRequest(
		serverAddress.getHostName(),
		serverAddress.getPort(),
		TestVersionHeaders.INSTANCE,
		EmptyMessageParameters.getInstance(),
		EmptyRequestBody.getInstance(),
		Collections.emptyList()
	);

	unspecifiedVersionResponse.get(5, TimeUnit.SECONDS);

	CompletableFuture<EmptyResponseBody> specifiedVersionResponse = restClient.sendRequest(
		serverAddress.getHostName(),
		serverAddress.getPort(),
		TestVersionHeaders.INSTANCE,
		EmptyMessageParameters.getInstance(),
		EmptyRequestBody.getInstance(),
		Collections.emptyList(),
		RestAPIVersion.V1
	);

	specifiedVersionResponse.get(5, TimeUnit.SECONDS);
}
 

public <M extends MessageHeaders<R, P, U>, U extends MessageParameters, R extends RequestBody, P extends ResponseBody> CompletableFuture<P> sendRequest(
		String targetAddress,
		int targetPort,
		M messageHeaders,
		U messageParameters,
		R request,
		Collection<FileUpload> fileUploads) throws IOException {
	return sendRequest(
		targetAddress,
		targetPort,
		messageHeaders,
		messageParameters,
		request,
		fileUploads,
		RestAPIVersion.getLatestVersion(messageHeaders.getSupportedAPIVersions()));
}
 

public <M extends MessageHeaders<R, P, U>, U extends MessageParameters, R extends RequestBody, P extends ResponseBody> CompletableFuture<P> sendRequest(
		String targetAddress,
		int targetPort,
		M messageHeaders,
		U messageParameters,
		R request,
		Collection<FileUpload> fileUploads) throws IOException {
	return sendRequest(
		targetAddress,
		targetPort,
		messageHeaders,
		messageParameters,
		request,
		fileUploads,
		RestAPIVersion.getLatestVersion(messageHeaders.getSupportedAPIVersions()));
}
 

@Test
public void testVersioning() throws Exception {
	CompletableFuture<EmptyResponseBody> unspecifiedVersionResponse = restClient.sendRequest(
		serverAddress.getHostName(),
		serverAddress.getPort(),
		TestVersionHeaders.INSTANCE,
		EmptyMessageParameters.getInstance(),
		EmptyRequestBody.getInstance(),
		Collections.emptyList()
	);

	unspecifiedVersionResponse.get(5, TimeUnit.SECONDS);

	CompletableFuture<EmptyResponseBody> specifiedVersionResponse = restClient.sendRequest(
		serverAddress.getHostName(),
		serverAddress.getPort(),
		TestVersionHeaders.INSTANCE,
		EmptyMessageParameters.getInstance(),
		EmptyRequestBody.getInstance(),
		Collections.emptyList(),
		RestAPIVersion.V1
	);

	specifiedVersionResponse.get(5, TimeUnit.SECONDS);
}
 

@Test
public void testExcludeFromDocumentation() throws Exception {
	File file = File.createTempFile("rest_v0_", ".html");
	RestAPIDocGenerator.createHtmlFile(
		new TestExcludeDocumentingRestEndpoint(),
		RestAPIVersion.V0,
		file.toPath());
	String actual = FileUtils.readFile(file, "UTF-8");

	assertThat(actual, containsString("/test/empty1"));
	assertThat(actual, containsString("This is a testing REST API."));
	assertThat(actual, containsString("/test/empty2"));
	assertThat(actual, containsString("This is another testing REST API."));
	assertThat(actual, not(containsString("/test/exclude1")));
	assertThat(actual, not(containsString("This REST API should not appear in the generated documentation.")));
	assertThat(actual, not(containsString("/test/exclude2")));
	assertThat(actual, not(containsString("This REST API should also not appear in the generated documentation.")));
}
 

@Test
public void testInvalidVersionRejection() throws Exception {
	try (final RestClient restClient = new RestClient(RestClientConfiguration.fromConfiguration(new Configuration()), Executors.directExecutor())) {
		CompletableFuture<EmptyResponseBody> invalidVersionResponse = restClient.sendRequest(
			unroutableIp,
			80,
			new TestMessageHeaders(),
			EmptyMessageParameters.getInstance(),
			EmptyRequestBody.getInstance(),
			Collections.emptyList(),
			RestAPIVersion.V0
		);
		Assert.fail("The request should have been rejected due to a version mismatch.");
	} catch (IllegalArgumentException e) {
		// expected
	}
}
 

@Test
public void testInvalidVersionRejection() throws Exception {
	try (final RestClient restClient = new RestClient(RestClientConfiguration.fromConfiguration(new Configuration()), Executors.directExecutor())) {
		CompletableFuture<EmptyResponseBody> invalidVersionResponse = restClient.sendRequest(
			unroutableIp,
			80,
			new TestMessageHeaders(),
			EmptyMessageParameters.getInstance(),
			EmptyRequestBody.getInstance(),
			Collections.emptyList(),
			RestAPIVersion.V0
		);
		Assert.fail("The request should have been rejected due to a version mismatch.");
	} catch (IllegalArgumentException e) {
		// expected
	}
}
 

@Test
public void testVersioning() throws Exception {
	CompletableFuture<EmptyResponseBody> unspecifiedVersionResponse = restClient.sendRequest(
		serverAddress.getHostName(),
		serverAddress.getPort(),
		TestVersionHeaders.INSTANCE,
		EmptyMessageParameters.getInstance(),
		EmptyRequestBody.getInstance(),
		Collections.emptyList()
	);

	unspecifiedVersionResponse.get(5, TimeUnit.SECONDS);

	CompletableFuture<EmptyResponseBody> specifiedVersionResponse = restClient.sendRequest(
		serverAddress.getHostName(),
		serverAddress.getPort(),
		TestVersionHeaders.INSTANCE,
		EmptyMessageParameters.getInstance(),
		EmptyRequestBody.getInstance(),
		Collections.emptyList(),
		RestAPIVersion.V1
	);

	specifiedVersionResponse.get(5, TimeUnit.SECONDS);
}
 

public <M extends MessageHeaders<R, P, U>, U extends MessageParameters, R extends RequestBody, P extends ResponseBody> CompletableFuture<P> sendRequest(
		String targetAddress,
		int targetPort,
		M messageHeaders,
		U messageParameters,
		R request,
		Collection<FileUpload> fileUploads) throws IOException {
	return sendRequest(
		targetAddress,
		targetPort,
		messageHeaders,
		messageParameters,
		request,
		fileUploads,
		RestAPIVersion.getLatestVersion(messageHeaders.getSupportedAPIVersions()));
}
 

private static void createHtmlFile(DocumentingRestEndpoint restEndpoint, RestAPIVersion apiVersion, Path outputFile) throws IOException {
	StringBuilder html = new StringBuilder();

	List<MessageHeaders> specs = restEndpoint.getSpecs().stream()
		.filter(spec -> spec.getSupportedAPIVersions().contains(apiVersion))
		.collect(Collectors.toList());
	specs.forEach(spec -> html.append(createHtmlEntry(spec)));

	Files.deleteIfExists(outputFile);
	Files.write(outputFile, html.toString().getBytes(StandardCharsets.UTF_8));
}
 

private static void checkAllEndpointsAndHandlersAreUnique(final List<Tuple2<RestHandlerSpecification, ChannelInboundHandler>> handlers) {
	// check for all handlers that
	// 1) the instance is only registered once
	// 2) only 1 handler is registered for each endpoint (defined by (version, method, url))
	// technically the first check is redundant since a duplicate instance also returns the same headers which
	// should fail the second check, but we get a better error message
	final Set<String> uniqueEndpoints = new HashSet<>();
	final Set<ChannelInboundHandler> distinctHandlers = Collections.newSetFromMap(new IdentityHashMap<>());
	for (Tuple2<RestHandlerSpecification, ChannelInboundHandler> handler : handlers) {
		boolean isNewHandler = distinctHandlers.add(handler.f1);
		if (!isNewHandler) {
			throw new FlinkRuntimeException("Duplicate REST handler instance found."
				+ " Please ensure each instance is registered only once.");
		}

		final RestHandlerSpecification headers = handler.f0;
		for (RestAPIVersion supportedAPIVersion : headers.getSupportedAPIVersions()) {
			final String parameterizedEndpoint = supportedAPIVersion.toString() + headers.getHttpMethod() + headers.getTargetRestEndpointURL();
			// normalize path parameters; distinct path parameters still clash at runtime
			final String normalizedEndpoint = parameterizedEndpoint.replaceAll(":[\\w-]+", ":param");
			boolean isNewEndpoint = uniqueEndpoints.add(normalizedEndpoint);
			if (!isNewEndpoint) {
				throw new FlinkRuntimeException(
					String.format(
						"REST handler registration overlaps with another registration for: version=%s, method=%s, url=%s.",
						supportedAPIVersion, headers.getHttpMethod(), headers.getTargetRestEndpointURL()));
			}
		}
	}
}
 

private static void registerHandler(Router router, Tuple2<RestHandlerSpecification, ChannelInboundHandler> specificationHandler, Logger log) {
	final String handlerURL = specificationHandler.f0.getTargetRestEndpointURL();
	// setup versioned urls
	for (final RestAPIVersion supportedVersion : specificationHandler.f0.getSupportedAPIVersions()) {
		final String versionedHandlerURL = '/' + supportedVersion.getURLVersionPrefix() + handlerURL;
		log.debug("Register handler {} under {}@{}.", specificationHandler.f1, specificationHandler.f0.getHttpMethod(), versionedHandlerURL);
		registerHandler(router, versionedHandlerURL, specificationHandler.f0.getHttpMethod(), specificationHandler.f1);
		if (supportedVersion.isDefaultVersion()) {
			// setup unversioned url for convenience and backwards compatibility
			log.debug("Register handler {} under {}@{}.", specificationHandler.f1, specificationHandler.f0.getHttpMethod(), handlerURL);
			registerHandler(router, handlerURL, specificationHandler.f0.getHttpMethod(), specificationHandler.f1);
		}
	}
}
 

@VisibleForTesting
static void createHtmlFile(DocumentingRestEndpoint restEndpoint, RestAPIVersion apiVersion, Path outputFile) throws IOException {
	StringBuilder html = new StringBuilder();

	List<MessageHeaders> specs = restEndpoint.getSpecs().stream()
		.filter(spec -> spec.getSupportedAPIVersions().contains(apiVersion))
		.filter(RestAPIDocGenerator::shouldBeDocumented)
		.collect(Collectors.toList());
	specs.forEach(spec -> html.append(createHtmlEntry(spec)));

	Files.deleteIfExists(outputFile);
	Files.write(outputFile, html.toString().getBytes(StandardCharsets.UTF_8));
}
 

/**
 * Generates the REST API documentation.
 *
 * @param args args[0] contains the directory into which the generated files are placed
 * @throws IOException if any file operation failed
 */
public static void main(String[] args) throws IOException {
	String outputDirectory = args[0];

	for (final RestAPIVersion apiVersion : RestAPIVersion.values()) {
		if (apiVersion == RestAPIVersion.V0) {
			// this version exists only for testing purposes
			continue;
		}
		createHtmlFile(
			new DocumentingDispatcherRestEndpoint(),
			apiVersion,
			Paths.get(outputDirectory, "rest_" + apiVersion.getURLVersionPrefix() + "_dispatcher.html"));
	}
}
 

/**
 * Generates the REST API documentation.
 *
 * @param args args[0] contains the directory into which the generated files are placed
 * @throws IOException if any file operation failed
 */
public static void main(String[] args) throws IOException {
	String outputDirectory = args[0];

	for (final RestAPIVersion apiVersion : RestAPIVersion.values()) {
		if (apiVersion == RestAPIVersion.V0) {
			// this version exists only for testing purposes
			continue;
		}
		createHtmlFile(
			new DocumentingDispatcherRestEndpoint(),
			apiVersion,
			Paths.get(outputDirectory, "rest_" + apiVersion.getURLVersionPrefix() + "_dispatcher.html"));
	}
}
 

private static void registerHandler(Router router, Tuple2<RestHandlerSpecification, ChannelInboundHandler> specificationHandler, Logger log) {
	final String handlerURL = specificationHandler.f0.getTargetRestEndpointURL();
	// setup versioned urls
	for (final RestAPIVersion supportedVersion : specificationHandler.f0.getSupportedAPIVersions()) {
		final String versionedHandlerURL = '/' + supportedVersion.getURLVersionPrefix() + handlerURL;
		log.debug("Register handler {} under {}@{}.", specificationHandler.f1, specificationHandler.f0.getHttpMethod(), versionedHandlerURL);
		registerHandler(router, versionedHandlerURL, specificationHandler.f0.getHttpMethod(), specificationHandler.f1);
		if (supportedVersion.isDefaultVersion()) {
			// setup unversioned url for convenience and backwards compatibility
			log.debug("Register handler {} under {}@{}.", specificationHandler.f1, specificationHandler.f0.getHttpMethod(), handlerURL);
			registerHandler(router, handlerURL, specificationHandler.f0.getHttpMethod(), specificationHandler.f1);
		}
	}
}
 

private static void createHtmlFile(DocumentingRestEndpoint restEndpoint, RestAPIVersion apiVersion, Path outputFile) throws IOException {
	StringBuilder html = new StringBuilder();

	List<MessageHeaders> specs = restEndpoint.getSpecs().stream()
		.filter(spec -> spec.getSupportedAPIVersions().contains(apiVersion))
		.collect(Collectors.toList());
	specs.forEach(spec -> html.append(createHtmlEntry(spec)));

	Files.deleteIfExists(outputFile);
	Files.write(outputFile, html.toString().getBytes(StandardCharsets.UTF_8));
}
 

/**
 * Generates the REST API documentation.
 *
 * @param args args[0] contains the directory into which the generated files are placed
 * @throws IOException if any file operation failed
 */
public static void main(String[] args) throws IOException {
	String outputDirectory = args[0];

	for (final RestAPIVersion apiVersion : RestAPIVersion.values()) {
		if (apiVersion == RestAPIVersion.V0) {
			// this version exists only for testing purposes
			continue;
		}
		createHtmlFile(
			new DocumentingDispatcherRestEndpoint(),
			apiVersion,
			Paths.get(outputDirectory, "rest_" + apiVersion.getURLVersionPrefix() + "_dispatcher.html"));
	}
}
 

private static void registerHandler(Router router, Tuple2<RestHandlerSpecification, ChannelInboundHandler> specificationHandler, Logger log) {
	final String handlerURL = specificationHandler.f0.getTargetRestEndpointURL();
	// setup versioned urls
	for (final RestAPIVersion supportedVersion : specificationHandler.f0.getSupportedAPIVersions()) {
		final String versionedHandlerURL = '/' + supportedVersion.getURLVersionPrefix() + handlerURL;
		log.debug("Register handler {} under {}@{}.", specificationHandler.f1, specificationHandler.f0.getHttpMethod(), versionedHandlerURL);
		registerHandler(router, versionedHandlerURL, specificationHandler.f0.getHttpMethod(), specificationHandler.f1);
		if (supportedVersion.isDefaultVersion()) {
			// setup unversioned url for convenience and backwards compatibility
			log.debug("Register handler {} under {}@{}.", specificationHandler.f1, specificationHandler.f0.getHttpMethod(), handlerURL);
			registerHandler(router, handlerURL, specificationHandler.f0.getHttpMethod(), specificationHandler.f1);
		}
	}
}
 

@Override
public Collection<RestAPIVersion> getSupportedAPIVersions() {
	return Collections.singleton(RestAPIVersion.V0);
}
 

@Override
public Collection<RestAPIVersion> getSupportedAPIVersions() {
	return Collections.singleton(RestAPIVersion.V1);
}
 

@Override
public Collection<RestAPIVersion> getSupportedAPIVersions() {
	return Collections.singleton(RestAPIVersion.V0);
}
 

@Override
public Collection<RestAPIVersion> getSupportedAPIVersions() {
	return Collections.singleton(RestAPIVersion.V1);
}
 

public <M extends MessageHeaders<R, P, U>, U extends MessageParameters, R extends RequestBody, P extends ResponseBody> CompletableFuture<P> sendRequest(
		String targetAddress,
		int targetPort,
		M messageHeaders,
		U messageParameters,
		R request,
		Collection<FileUpload> fileUploads,
		RestAPIVersion apiVersion) throws IOException {
	Preconditions.checkNotNull(targetAddress);
	Preconditions.checkArgument(NetUtils.isValidHostPort(targetPort), "The target port " + targetPort + " is not in the range [0, 65535].");
	Preconditions.checkNotNull(messageHeaders);
	Preconditions.checkNotNull(request);
	Preconditions.checkNotNull(messageParameters);
	Preconditions.checkNotNull(fileUploads);
	Preconditions.checkState(messageParameters.isResolved(), "Message parameters were not resolved.");

	if (!messageHeaders.getSupportedAPIVersions().contains(apiVersion)) {
		throw new IllegalArgumentException(String.format(
			"The requested version %s is not supported by the request (method=%s URL=%s). Supported versions are: %s.",
			apiVersion,
			messageHeaders.getHttpMethod(),
			messageHeaders.getTargetRestEndpointURL(),
			messageHeaders.getSupportedAPIVersions().stream().map(RestAPIVersion::getURLVersionPrefix).collect(Collectors.joining(","))));
	}

	String versionedHandlerURL = "/" + apiVersion.getURLVersionPrefix() + messageHeaders.getTargetRestEndpointURL();
	String targetUrl = MessageParameters.resolveUrl(versionedHandlerURL, messageParameters);

	LOG.debug("Sending request of class {} to {}:{}{}", request.getClass(), targetAddress, targetPort, targetUrl);
	// serialize payload
	StringWriter sw = new StringWriter();
	objectMapper.writeValue(sw, request);
	ByteBuf payload = Unpooled.wrappedBuffer(sw.toString().getBytes(ConfigConstants.DEFAULT_CHARSET));

	Request httpRequest = createRequest(targetAddress + ':' + targetPort, targetUrl, messageHeaders.getHttpMethod().getNettyHttpMethod(), payload, fileUploads);

	final JavaType responseType;

	final Collection<Class<?>> typeParameters = messageHeaders.getResponseTypeParameters();

	if (typeParameters.isEmpty()) {
		responseType = objectMapper.constructType(messageHeaders.getResponseClass());
	} else {
		responseType = objectMapper.getTypeFactory().constructParametricType(
			messageHeaders.getResponseClass(),
			typeParameters.toArray(new Class<?>[typeParameters.size()]));
	}

	return submitRequest(targetAddress, targetPort, httpRequest, responseType);
}
 

public <M extends MessageHeaders<R, P, U>, U extends MessageParameters, R extends RequestBody, P extends ResponseBody> CompletableFuture<P> sendRequest(
		String targetAddress,
		int targetPort,
		M messageHeaders,
		U messageParameters,
		R request,
		Collection<FileUpload> fileUploads,
		RestAPIVersion apiVersion) throws IOException {
	Preconditions.checkNotNull(targetAddress);
	Preconditions.checkArgument(0 <= targetPort && targetPort < 65536, "The target port " + targetPort + " is not in the range (0, 65536].");
	Preconditions.checkNotNull(messageHeaders);
	Preconditions.checkNotNull(request);
	Preconditions.checkNotNull(messageParameters);
	Preconditions.checkNotNull(fileUploads);
	Preconditions.checkState(messageParameters.isResolved(), "Message parameters were not resolved.");

	if (!messageHeaders.getSupportedAPIVersions().contains(apiVersion)) {
		throw new IllegalArgumentException(String.format(
			"The requested version %s is not supported by the request (method=%s URL=%s). Supported versions are: %s.",
			apiVersion,
			messageHeaders.getHttpMethod(),
			messageHeaders.getTargetRestEndpointURL(),
			messageHeaders.getSupportedAPIVersions().stream().map(RestAPIVersion::getURLVersionPrefix).collect(Collectors.joining(","))));
	}

	String versionedHandlerURL = "/" + apiVersion.getURLVersionPrefix() + messageHeaders.getTargetRestEndpointURL();
	String targetUrl = MessageParameters.resolveUrl(versionedHandlerURL, messageParameters);

	LOG.debug("Sending request of class {} to {}:{}{}", request.getClass(), targetAddress, targetPort, targetUrl);
	// serialize payload
	StringWriter sw = new StringWriter();
	objectMapper.writeValue(sw, request);
	ByteBuf payload = Unpooled.wrappedBuffer(sw.toString().getBytes(ConfigConstants.DEFAULT_CHARSET));

	Request httpRequest = createRequest(targetAddress + ':' + targetPort, targetUrl, messageHeaders.getHttpMethod().getNettyHttpMethod(), payload, fileUploads);

	final JavaType responseType;

	final Collection<Class<?>> typeParameters = messageHeaders.getResponseTypeParameters();

	if (typeParameters.isEmpty()) {
		responseType = objectMapper.constructType(messageHeaders.getResponseClass());
	} else {
		responseType = objectMapper.getTypeFactory().constructParametricType(
			messageHeaders.getResponseClass(),
			typeParameters.toArray(new Class<?>[typeParameters.size()]));
	}

	return submitRequest(targetAddress, targetPort, httpRequest, responseType);
}
 

@Override
public Collection<RestAPIVersion> getSupportedAPIVersions() {
	return Collections.singleton(RestAPIVersion.V1);
}
 

public RestAPIStabilityTest(final RestAPIVersion apiVersion) {
	this.apiVersion = apiVersion;
}
 

@Parameterized.Parameters(name = "version = {0}")
public static Iterable<RestAPIVersion> getStableVersions() {
	return Arrays.stream(RestAPIVersion.values())
		.filter(RestAPIVersion::isStableVersion)
		.collect(Collectors.toList());
}
 

@Override
public Collection<RestAPIVersion> getSupportedAPIVersions() {
	return Collections.singleton(RestAPIVersion.V0);
}