OIA-41: Support flow persistence

api/pom.xml

@@ -2,7 +2,7 @@
     <parent>
         <groupId>org.opennms.integration.api</groupId>
         <artifactId>api-project</artifactId>
-        <version>1.0.3-SNAPSHOT</version>
+        <version>1.1.0-SNAPSHOT</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <artifactId>api</artifactId>

api/src/main/java/org/opennms/integration/api/v1/flows/Flow.java

@@ -0,0 +1,200 @@
+/*******************************************************************************
+ * This file is part of OpenNMS(R).
+ *
+ * Copyright (C) 2022 The OpenNMS Group, Inc.
+ * OpenNMS(R) is Copyright (C) 1999-2022 The OpenNMS Group, Inc.
+ *
+ * OpenNMS(R) is a registered trademark of The OpenNMS Group, Inc.
+ *
+ * OpenNMS(R) is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License,
+ * or (at your option) any later version.
+ *
+ * OpenNMS(R) is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with OpenNMS(R).  If not, see:
+ *      http://www.gnu.org/licenses/
+ *
+ * For more information contact:
+ *     OpenNMS(R) Licensing <license@opennms.org>
+ *     http://www.opennms.org/
+ *     http://www.opennms.com/
+ *******************************************************************************/
+
+package org.opennms.integration.api.v1.flows;
+
+import java.time.Duration;
+import java.time.Instant;
+import java.util.List;
+import java.util.Optional;
+
+import org.opennms.integration.api.v1.annotations.Consumable;
+
+/**
+ * A network flow.
+ *
+ * Represents statistics about the communication between two systems.
+ *
+ * @since 1.1.0
+ */
+@Consumable
+public interface Flow {
+    /**
+     * The application as deduced by the classification engine.
+     *
+     * @return the application name
+     */
+    String getApplication();
+
+    /**
+     * The IP address of the source exporting this flow.
+     *
+     * @return the IP address
+     */
+    String getHost();
+
+    /**
+     * The location in which the flow was received.
+     *
+     * @return the location name
+     */
+    String getLocation();
+
+    Locality getSrcLocality();
+
+    Locality getDstLocality();
+
+    Locality getFlowLocality();
+
+    NodeInfo getSrcNodeInfo();
+
+    NodeInfo getDstNodeInfo();
+
+    NodeInfo getExporterNodeInfo();
+
+    Duration getClockCorrection();
+
+    Instant getTimestamp();
+
+    Instant getFirstSwitched();
+
+    Instant getDeltaSwitched();
+
+    Instant getLastSwitched();
+
+    Instant getReceivedAt();
+
+    Long getBytes();
+
+    Direction getDirection();
+
+    String getDstAddr();
+
+    Optional<String> getDstAddrHostname();
+
+    Long getDstAs();
+
+    Integer getDstMaskLen();
+
+    Integer getDstPort();
+
+    Integer getEngineId();
+
+    Integer getEngineType();
+
+    int getFlowRecords();
+
+    long getFlowSeqNum();
+
+    Integer getInputSnmp();
+
+    Integer getIpProtocolVersion();
+
+    String getNextHop();
+
+    Optional<String> getNextHopHostname();
+
+    Integer getOutputSnmp();
+
+    Long getPackets();
+
+    Integer getProtocol();
+
+    SamplingAlgorithm getSamplingAlgorithm();
+
+    Double getSamplingInterval();
+
+    String getSrcAddr();
+
+    Optional<String> getSrcAddrHostname();
+
+    Long getSrcAs();
+
+    Integer getSrcMaskLen();
+
+    Integer getSrcPort();
+
+    Integer getTcpFlags();
+
+    Integer getTos();
+
+    NetflowVersion getNetflowVersion();
+
+    Integer getVlan();
+
+    Integer getDscp();
+
+    Integer getEcn();
+
+    String getConvoKey();
+
+    @Consumable
+    public enum Locality {
+        PUBLIC, PRIVATE
+    }
+
+    @Consumable
+    public interface NodeInfo {
+        int getInterfaceId();
+
+        int getNodeId();
+
+        String getForeignId();
+
+        String getForeignSource();
+
+        List<String> getCategories();
+    }
+
+    @Consumable
+    enum NetflowVersion {
+        V5,
+        V9,
+        IPFIX,
+        SFLOW,
+    }
+
+    @Consumable
+    enum Direction {
+        INGRESS,
+        EGRESS,
+        UNKNOWN,
+    }
+
+    @Consumable
+    enum SamplingAlgorithm {
+        Unassigned,
+        SystematicCountBasedSampling,
+        SystematicTimeBasedSampling,
+        RandomNOutOfNSampling,
+        UniformProbabilisticSampling,
+        PropertyMatchFiltering,
+        HashBasedFiltering,
+        FlowStateDependentIntermediateFlowSelectionProcess;
+    }
+}

api/src/main/java/org/opennms/integration/api/v1/flows/FlowException.java

@@ -0,0 +1,44 @@
+/*******************************************************************************
+ * This file is part of OpenNMS(R).
+ *
+ * Copyright (C) 2022 The OpenNMS Group, Inc.
+ * OpenNMS(R) is Copyright (C) 1999-2022 The OpenNMS Group, Inc.
+ *
+ * OpenNMS(R) is a registered trademark of The OpenNMS Group, Inc.
+ *
+ * OpenNMS(R) is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License,
+ * or (at your option) any later version.
+ *
+ * OpenNMS(R) is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with OpenNMS(R).  If not, see:
+ *      http://www.gnu.org/licenses/
+ *
+ * For more information contact:
+ *     OpenNMS(R) Licensing <license@opennms.org>
+ *     http://www.opennms.org/
+ *     http://www.opennms.com/
+ *******************************************************************************/
+
+package org.opennms.integration.api.v1.flows;
+
+public class FlowException extends Exception {
+
+    public FlowException(final String message) {
+        super(message);
+    }
+
+    public FlowException(final String message, final Throwable cause) {
+        super(message, cause);
+    }
+
+    public FlowException(final Throwable cause) {
+        super(cause);
+    }
+}

api/src/main/java/org/opennms/integration/api/v1/flows/FlowRepository.java

@@ -0,0 +1,51 @@
+/*******************************************************************************
+ * This file is part of OpenNMS(R).
+ *
+ * Copyright (C) 2022 The OpenNMS Group, Inc.
+ * OpenNMS(R) is Copyright (C) 1999-2022 The OpenNMS Group, Inc.
+ *
+ * OpenNMS(R) is a registered trademark of The OpenNMS Group, Inc.
+ *
+ * OpenNMS(R) is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License,
+ * or (at your option) any later version.
+ *
+ * OpenNMS(R) is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with OpenNMS(R).  If not, see:
+ *      http://www.gnu.org/licenses/
+ *
+ * For more information contact:
+ *     OpenNMS(R) Licensing <license@opennms.org>
+ *     http://www.opennms.org/
+ *     http://www.opennms.com/
+ *******************************************************************************/
+
+package org.opennms.integration.api.v1.flows;
+
+import java.util.Collection;
+
+import org.opennms.integration.api.v1.annotations.Exposable;
+
+/**
+ * Persistence interface for flows.
+ *
+ * After parsing and processing of received flows, the result is passed to all exposed instances of this interface.
+ */
+@Exposable
+public interface FlowRepository {
+
+    /**
+     * Persist a batch of flows.
+     *
+     * @param flows the flows which should be persisted
+     *
+     * @throws FlowException on any error happening during processing.
+     */
+    void persist(final Collection<? extends Flow> flows) throws FlowException;
+}

archetypes/example-kar-plugin/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>org.opennms.integration.api</groupId>
         <artifactId>archetypes</artifactId>
-        <version>1.0.3-SNAPSHOT</version>
+        <version>1.1.0-SNAPSHOT</version>
     </parent>
     <artifactId>example-kar-plugin</artifactId>
     <packaging>maven-archetype</packaging>

archetypes/pom.xml

@@ -2,7 +2,7 @@
     <parent>
         <groupId>org.opennms.integration.api</groupId>
         <artifactId>api-project</artifactId>
-        <version>1.0.3-SNAPSHOT</version>
+        <version>1.1.0-SNAPSHOT</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <artifactId>archetypes</artifactId>

common/pom.xml

@@ -2,7 +2,7 @@
     <parent>
         <groupId>org.opennms.integration.api</groupId>
         <artifactId>api-project</artifactId>
-        <version>1.0.3-SNAPSHOT</version>
+        <version>1.1.0-SNAPSHOT</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <artifactId>common</artifactId>

config/pom.xml

@@ -2,7 +2,7 @@
     <parent>
         <groupId>org.opennms.integration.api</groupId>
         <artifactId>api-project</artifactId>
-        <version>1.0.3-SNAPSHOT</version>
+        <version>1.1.0-SNAPSHOT</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <artifactId>config</artifactId>

karaf-features/pom.xml

@@ -2,7 +2,7 @@
     <parent>
         <groupId>org.opennms.integration.api</groupId>
         <artifactId>api-project</artifactId>
-        <version>1.0.3-SNAPSHOT</version>
+        <version>1.1.0-SNAPSHOT</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <artifactId>karaf-features</artifactId>

pom.xml

@@ -3,7 +3,7 @@
     <groupId>org.opennms.integration.api</groupId>
     <artifactId>api-project</artifactId>
     <packaging>pom</packaging>
-    <version>1.0.3-SNAPSHOT</version>
+    <version>1.1.0-SNAPSHOT</version>
     <name>OpenNMS Integration API :: Parent</name>
     <url>https://github.com/OpenNMS/opennms-integration-api</url>
     <description>Integration and extension API for OpenNMS</description>

sample/pom.xml

@@ -2,7 +2,7 @@
     <parent>
         <groupId>org.opennms.integration.api</groupId>
         <artifactId>api-project</artifactId>
-        <version>1.0.3-SNAPSHOT</version>
+        <version>1.1.0-SNAPSHOT</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <groupId>org.opennms.integration.api.sample</groupId>

test-api/pom.xml

@@ -2,7 +2,7 @@
     <parent>
         <groupId>org.opennms.integration.api</groupId>
         <artifactId>api-project</artifactId>
-        <version>1.0.3-SNAPSHOT</version>
+        <version>1.1.0-SNAPSHOT</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <artifactId>test-api</artifactId>

test-suites/pom.xml

@@ -2,7 +2,7 @@
     <parent>
         <groupId>org.opennms.integration.api</groupId>
         <artifactId>api-project</artifactId>
-        <version>1.0.3-SNAPSHOT</version>
+        <version>1.1.0-SNAPSHOT</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <artifactId>test-suites</artifactId>

test-suites/tss-tests/pom.xml

@@ -3,7 +3,7 @@
     <parent>
         <groupId>org.opennms.integration.api</groupId>
         <artifactId>test-suites</artifactId>
-        <version>1.0.3-SNAPSHOT</version>
+        <version>1.1.0-SNAPSHOT</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
     <artifactId>tss-tests</artifactId>