org.openbase.jul.extension.protobuf.iface.DataBuilderProvider Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jul.extension.protobuf Show documentation
The newest version!
package org.openbase.jul.extension.protobuf.iface;

/*-
 * #%L
 * JUL Extension Protobuf
 * %%
 * Copyright (C) 2015 - 2022 openbase.org
 * %%
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 * 
 * This program 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 General Lesser Public License for more details.
 * 
 * You should have received a copy of the GNU General Lesser Public
 * License along with this program.  If not, see
 * .
 * #L%
 */

import com.google.protobuf.AbstractMessage;
import org.openbase.jul.extension.protobuf.BuilderSyncSetup;
import org.openbase.jul.extension.protobuf.BuilderSyncSetup.NotificationStrategy;
import org.openbase.jul.extension.protobuf.ClosableDataBuilder;

/**
 * * @author Tamino Huxohl
 *
 * @param   Message
 * @param  Builder
 */
public interface DataBuilderProvider> {

    MB cloneDataBuilder();

    BuilderSyncSetup getBuilderSetup();

    /**
     * This method generates a closable data builder wrapper including the
     * internal builder instance. Be informed that the internal builder is
     * directly locked and all internal builder operations are queued. Therefore please
     * call the close method soon as possible to release the builder lock after
     * you builder modifications, otherwise the overall processing pipeline is
     * delayed.
     *
     *
     *      * {@code Usage Example:
     *
     *     try (ClosableDataBuilder dataBuilder = getDataBuilder(this)) {
     *         dataBuilder.getInternalBuilder().setMotionState(motion);
     *     } catch (Exception ex) {
     *         throw new CouldNotPerformException("Could not apply data change!", ex);
     *     }
     * }
     *  In this example the ClosableDataBuilder.close method is be called
     * in background after leaving the try brackets.
     *
     * @param consumer
     *
     * @return a new builder wrapper with a locked builder instance.
     */
    ClosableDataBuilder getDataBuilder(final Object consumer);

    /**
     * This method generates a closable data builder wrapper including the
     * internal builder instance. Be informed that the internal builder is
     * directly locked and all internal builder operations are queued. Therefore please
     * call the close method soon as possible to release the builder lock after
     * you builder modifications, otherwise the overall processing pipeline is
     * delayed.
     *
     *
     *      * {@code Usage Example:
     *
     *     try (ClosableDataBuilder dataBuilder = getDataBuilder(this)) {
     *         dataBuilder.getInternalBuilder().setMotionState(motion);
     *     } catch (Exception ex) {
     *         throw new CouldNotPerformException("Could not apply data change!", ex);
     *     }
     * }
     *  In this example the ClosableDataBuilder.close method is be called
     * in background after leaving the try brackets.
     *
     * @param consumer
     * @param notificationStrategy the notification strategy to follow after unlocking the data lock.
     *
     * @return a new builder wrapper with a locked builder instance.
     */
    ClosableDataBuilder getDataBuilder(final Object consumer, final NotificationStrategy notificationStrategy);

    /**
     * This method generates a closable data builder wrapper including the
     * internal builder instance. Be informed that the internal builder is
     * directly locked and all internal builder operations are queued. Therefore please
     * call the close method soon as possible to release the builder lock after
     * you builder modifications, otherwise the overall processing pipeline is
     * delayed.
     *
     *
     *      * {@code Usage Example:
     *
     *     try (ClosableDataBuilder dataBuilder = getDataBuilder(this)) {
     *         dataBuilder.getInternalBuilder().setMotionState(motion);
     *     } catch (Exception ex) {
     *         throw new CouldNotPerformException("Could not apply data change!", ex);
     *     }
     * }
     *  In this example the ClosableDataBuilder.close method is be called
     * in background after leaving the try brackets.
     *
     * @param consumer
     *
     * @return a new builder wrapper with a locked builder instance.
     *
     * @throws InterruptedException is thrown in case the thread is externally interrupted while waiting for the builder lock.
     */
    ClosableDataBuilder getDataBuilderInterruptible(final Object consumer) throws InterruptedException;

    /**
     * This method generates a closable data builder wrapper including the
     * internal builder instance. Be informed that the internal builder is
     * directly locked and all internal builder operations are queued. Therefore please
     * call the close method soon as possible to release the builder lock after
     * you builder modifications, otherwise the overall processing pipeline is
     * delayed.
     *
     *
     *      * {@code Usage Example:
     *
     *     try (ClosableDataBuilder dataBuilder = getDataBuilder(this)) {
     *         dataBuilder.getInternalBuilder().setMotionState(motion);
     *     } catch (Exception ex) {
     *         throw new CouldNotPerformException("Could not apply data change!", ex);
     *     }
     * }
     *  In this example the ClosableDataBuilder.close method is be called
     * in background after leaving the try brackets.
     *
     * @param consumer
     * @param notificationStrategy the notification strategy to follow after unlocking the data lock.
     *
     * @return a new builder wrapper with a locked builder instance.
     *
     * @throws InterruptedException is thrown in case the thread is externally interrupted while waiting for the builder lock.
     */
    ClosableDataBuilder getDataBuilderInterruptible(final Object consumer, final NotificationStrategy notificationStrategy) throws InterruptedException;
}