protocols/p4runtime/api/src/main/java/org/onosproject/p4runtime/api/P4RuntimeController.java

/*
 * Copyright 2017-present Open Networking Foundation
 *
 * Licensed 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.onosproject.p4runtime.api;

import com.google.common.annotations.Beta;
import org.onosproject.event.ListenerService;
import org.onosproject.net.DeviceId;
import org.onosproject.net.device.ChannelListener;

/**
 * Controller of P4Runtime devices.
 */
@Beta
public interface P4RuntimeController extends ListenerService<P4RuntimeEvent, P4RuntimeEventListener> {

    /**
     * Instantiates a new client to operate on a P4Runtime device identified by
     * the given information. As a result of this method, a {@link
     * P4RuntimeClient} can be later obtained by invoking {@link
     * #getClient(DeviceId)}. Returns true if the client was created and the
     * channel to the device is open, false otherwise.
     * <p>
     * Only one client can exist for the same device ID. Calls to this method
     * are idempotent for the same [device ID, address, port, p4DeviceId] tuple,
     * i.e. returns true if such client already exists but a new one is not
     * created. Throws an {@link IllegalStateException} if a client for device
     * ID already exists but for different [address, port, p4DeviceId].
     *
     * @param deviceId   device identifier
     * @param serverAddr address of the P4Runtime server
     * @param serverPort port of the P4Runtime server
     * @param p4DeviceId P4Runtime-specific device identifier
     * @return true if the client was created and the channel to the device is
     * open
     * @throws IllegalStateException if a client already exists for this device
     *                               ID but for different [address, port,
     *                               p4DeviceId].
     */
    boolean createClient(DeviceId deviceId, String serverAddr, int serverPort,
                         long p4DeviceId);

    /**
     * Returns a client to operate on the given device.
     *
     * @param deviceId device identifier
     * @return client instance
     * @throws IllegalStateException if no client exists for the given device identifier
     */
    P4RuntimeClient getClient(DeviceId deviceId);

    /**
     * Removes the client for the given device. If no client exists for the given device identifier, the
     * result is a no-op.
     *
     * @param deviceId device identifier
     */
    void removeClient(DeviceId deviceId);

    /**
     * Returns true if a client exists for the given device identifier, false otherwise.
     *
     * @param deviceId device identifier
     * @return true if client exists, false otherwise.
     */
    boolean hasClient(DeviceId deviceId);

    /**
     * Returns true if the P4Runtime server running on the given device is reachable, i.e. the channel is open and the
     * server is able to respond to RPCs, false otherwise. Reachability can be tested only if a client was previously
     * created using {@link #createClient(DeviceId, String, int, long)}, otherwise this method returns false.
     *
     * @param deviceId device identifier.
     * @return true if a client was created and is able to contact the P4Runtime server, false otherwise.
     */
    boolean isReacheable(DeviceId deviceId);

    /**
     * Gets new election id for device arbitration request.
     *
     * @return the election id
     */
    long getNewMasterElectionId();

    /**
     * Adds a listener for P4Runtime client-server channel events.
     * If the channel for the device is not present and/or established the listener will get notified
     * only after channel setup.
     *
     * @param deviceId device identifier
     * @param listener the channel listener
     */
    void addChannelListener(DeviceId deviceId, ChannelListener listener);

    /**
     * Removes the listener for P4Runtime client-server channel events.
     *
     * @param deviceId device identifier
     * @param listener the channel listener
     */
    void removeChannelListener(DeviceId deviceId, ChannelListener listener);
}