org.apache.nifi.registry.flow.FlowRegistryClient Maven / Gradle / Ivy
The newest version!
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.nifi.registry.flow;
import org.apache.nifi.components.ConfigurableComponent;
import java.io.IOException;
import java.util.Optional;
import java.util.Set;
import java.util.UUID;
/**
*
* Represents and external source, where flows might be stored and retrieved from. The interface provides
* the possibility to have multiple different types of registries backing NiFi.
*
*
*
* FlowRegistryClients are discovered using Java's
* ServiceLoader mechanism. As a result, all implementations must
* follow these rules:
*
*
* - The implementation must implement this interface.
* - The implementation must have a file named
* org.apache.nifi.registry.flow.FlowRegistryClient located within the jar's
*
META-INF/services directory. This file contains a list of
* fully-qualified class names of all FlowRegistryClients in the
* jar, one-per-line.
* - The implementation must support a default constructor.
*
*
*
* FlowRegistryClient instances are always considered "active" and approachable when the validation status is considered as valid.
* Therefore after initialize, implementations must expect incoming requests any time.
*
*
*
* The argument list of the request methods contain instances FlowRegistryClientConfigurationContext, which always contains the current
* state of the properties. Caching properties between method calls is not recommended.
*
*
*/
public interface FlowRegistryClient extends ConfigurableComponent {
String DEFAULT_BRANCH_NAME = "main";
void initialize(FlowRegistryClientInitializationContext context);
/**
* Decides if the given location is applicable by the repository instance. The format depends on the implementation.
*
* @param context Configuration context.
* @param location The location of versioned flow to check.
*
* @return True in case of the given storage location is applicable, false otherwise. An applicable location does not
* mean that the flow specified by the location is stored in the registry. Depending on the implementation it might be
* merely a static check on the format of the location string. In case of uncertainty, NiFi tries to load the versioned
* flow from registries with true return value first.
*/
boolean isStorageLocationApplicable(FlowRegistryClientConfigurationContext context, String location);
/**
* Indicates if the registry supports branching.
*
* If the registry does not supporting branching, then this method should return false and the registry client should use
* the default implementations of getBranches and getDefaultBranch.
*
* If the registry does support branching, then this method should return true and the registry client should use
* override getBranches and getDefaultBranch to provide appropriate implementations.
*
* @param context Configuration context
* @return true if the registry supports branching, false otherwise
*/
default boolean isBranchingSupported(final FlowRegistryClientConfigurationContext context) {
return false;
}
/**
* Get the available branches. Should return at least one branch that matches the response of getDefaultBranch.
*
* @param context Configuration context
* @return the set of available branches
*
* @throws FlowRegistryException If an issue happens during processing the request.
* @throws IOException If there is issue with the communication between NiFi and the Flow Registry.
*/
default Set getBranches(final FlowRegistryClientConfigurationContext context) throws FlowRegistryException, IOException {
return Set.of(getDefaultBranch(context));
}
/**
* Gets the default branch. Must return a non-null FlowRegistryBranch instance with a non-null name.
* The interface provides a default implementation which will return a branch named 'main'.
*
* @param context Configuration context
* @return the default branch
*
* @throws FlowRegistryException If an issue happens during processing the request.
* @throws IOException If there is issue with the communication between NiFi and the Flow Registry.
*/
default FlowRegistryBranch getDefaultBranch(final FlowRegistryClientConfigurationContext context) throws FlowRegistryException, IOException {
final FlowRegistryBranch branch = new FlowRegistryBranch();
branch.setName(DEFAULT_BRANCH_NAME);
return branch;
}
/**
* Gets the buckets for the specified user.
*
* @param context Configuration context.
* @param branch the branch
*
* @return Buckets for this user. In case there are no available buckets for the user the result will be an empty set.
*
* @throws FlowRegistryException If an issue happens during processing the request.
* @throws IOException If there is issue with the communication between NiFi and the Flow Registry.
*/
Set getBuckets(FlowRegistryClientConfigurationContext context, String branch) throws FlowRegistryException, IOException;
/**
* Gets the bucket with the given id.
*
* @param context Configuration context.
* @param bucketLocation The location of the bucket.
* @return The bucket with the given id.
*
* @throws NoSuchBucketException If there is no bucket in the Registry with the given id.
* @throws FlowRegistryException If an issue happens during processing the request.
* @throws IOException If there is issue with the communication between NiFi and the Flow Registry.
*/
FlowRegistryBucket getBucket(FlowRegistryClientConfigurationContext context, BucketLocation bucketLocation) throws FlowRegistryException, IOException;
/**
* Registers the given RegisteredFlow into the Flow Registry.
*
* @param context Configuration context.
* @param flow The RegisteredFlow to add to the Registry.
*
* @return The fully populated RegisteredFlow
*
* @throws FlowAlreadyExistsException If a Flow with the given identifier already exists in the registry.
* @throws FlowRegistryException If an issue happens during processing the request.
* @throws IOException If there is issue with the communication between NiFi and the Flow Registry.
*/
RegisteredFlow registerFlow(FlowRegistryClientConfigurationContext context, RegisteredFlow flow) throws FlowRegistryException, IOException;
/**
* Deletes the specified flow from the Flow Registry.
*
* @param context Configuration context.
* @param flowLocation the location of the flow
*
* @return The deleted Flow.
*
* @throws FlowRegistryException If an issue happens during processing the request.
* @throws IOException If there is issue with the communication between NiFi and the Flow Registry.
*/
RegisteredFlow deregisterFlow(FlowRegistryClientConfigurationContext context, FlowLocation flowLocation) throws FlowRegistryException, IOException;
/**
* Retrieves a flow by bucket id and Flow id.
*
* @param context Configuration context.
* @param flowLocation the location of the flow
*
* @return The Flow for the given bucket and Flow id's.
*
* @throws NoSuchFlowException If there is no Flow in the bucket with the given id.
* @throws FlowRegistryException If an issue happens during processing the request.
* @throws IOException If there is issue with the communication between NiFi and the Flow Registry.
*/
RegisteredFlow getFlow(FlowRegistryClientConfigurationContext context, FlowLocation flowLocation) throws FlowRegistryException, IOException;
/**
* Retrieves the set of all Flows for the specified bucket.
*
* @param context Configuration context.
* @param bucketLocation the location of the bucket
*
* @return The set of all Flows from the specified bucket. In case there are no available flows in the bucket the result will be an empty set.
*
* @throws FlowRegistryException If an issue happens during processing the request.
* @throws IOException If there is issue with the communication between NiFi and the Flow Registry.
*/
Set getFlows(FlowRegistryClientConfigurationContext context, BucketLocation bucketLocation) throws FlowRegistryException, IOException;
/**
* Retrieves the contents of the flow snapshot with the given Bucket id, Flow id, and version, from the Registry.
*
* @param context Configuration context.
* @param flowVersionLocation the location of the flow version
*
* @return The contents of the Flow from the Flow Registry.
*
* @throws NoSuchFlowVersionException If there is no version of the Flow with the given version number.
* @throws FlowRegistryException If an issue happens during processing the request.
* @throws IOException If there is issue with the communication between NiFi and the Flow Registry.
*/
RegisteredFlowSnapshot getFlowContents(FlowRegistryClientConfigurationContext context, FlowVersionLocation flowVersionLocation) throws FlowRegistryException, IOException;
/**
* Adds the given snapshot to the Flow Registry for the given Flow.
*
* @param context Configuration context.
* @param flowSnapshot The flow snapshot to register.
* @param action The register action
*
* @return The flow snapshot.
*
* @throws FlowRegistryException If an issue happens during processing the request.
* @throws IOException If there is issue with the communication between NiFi and the Flow Registry.
*/
RegisteredFlowSnapshot registerFlowSnapshot(FlowRegistryClientConfigurationContext context, RegisteredFlowSnapshot flowSnapshot, RegisterAction action) throws FlowRegistryException, IOException;
/**
* Retrieves the set of all versions of the specified flow.
*
* @param context Configuration context.
* @param flowLocation the location of the flow
*
* @return The set of all versions of the specified flow. In case there are no available versions for the specified flow the result will be an empty set.
*
* @throws FlowRegistryException If an issue happens during processing the request.
* @throws IOException If there is issue with the communication between NiFi and the Flow Registry.
*/
Set getFlowVersions(FlowRegistryClientConfigurationContext context, FlowLocation flowLocation) throws FlowRegistryException, IOException;
/**
* Returns the latest (most recent) version of the Flow in the Flow Registry for the given bucket and Flow.
*
* @param context Configuration context.
* @param flowLocation the location of the flow
*
* @return an Optional containing the latest version of the flow, or empty if no versions exist for the flow
*
* @throws FlowRegistryException If an issue happens during processing the request.
* @throws IOException If there is issue with the communication between NiFi and the Flow Registry.
*/
Optional getLatestVersion(FlowRegistryClientConfigurationContext context, FlowLocation flowLocation) throws FlowRegistryException, IOException;
/**
* Generates the id for registering a flow.
*
* @param flowName the name of the flow
* @return the generated id
*/
default String generateFlowId(final String flowName) {
return UUID.randomUUID().toString();
}
}