package org.apache.plc4x.java.api.connection;

import org.apache.plc4x.java.api.exceptions.PlcConnectionException;
import org.apache.plc4x.java.api.exceptions.PlcInvalidAddressException;
import org.apache.plc4x.java.api.model.Address;

import java.util.Optional;

/**
 * Interface defining the most basic methods a PLC4X connection should support.
 * This generally handles the connection establishment itself and the parsing of
 * address strings to the platform dependent Address instances.
 * <p>
 * The individual operations are then defined by other interfaces within this package.
 */
public interface PlcConnection extends AutoCloseable {

    /**
     * Established the connection to the remote PLC.
     *
     * @throws PlcConnectionException an exception if the connection attempt failed.
     */
    void connect() throws PlcConnectionException;

    /**
     * Returns true if the PlcConnection is connected to a remote PLC.
     *
     * @return true, if connected, false, if not.
     */
    boolean isConnected();

    /**
     * Closes the connection to the remote PLC.
     *
     * @throws Exception an exception if shutting down the connection failed.
     */
    @Override
    void close() throws Exception;

    /**
     * Parses a PLC/protocol dependent query string into a PlcQuery object.
     *
     * @param queryString String representation of a query for the current type of PLC/protocol.
     * @return PlcQuery object containing all query data.
     * @throws PlcInvalidQueryException an exception if there was a problem parsing the query string.
     */
    PlcQuery prepareQuery(String queryString) throws PlcInvalidQueryException;

    Optional<PlcReader> getReader();

    Optional<PlcWriter> getWriter();

    Optional<PlcSubscriber> getSubscriber();
}