io.statusmachina.core.api.MachineBuilder Maven / Gradle / Ivy

Go to download
/*
 *
 * Copyright 2019 <---> Present Status Machina Contributors (https://github.com/entzik/status-machina/graphs/contributors)
 *
 * 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
 *
 * This software 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 io.statusmachina.core.api;

import io.statusmachina.core.spi.MachinePersistenceCallback;

import java.util.Map;

/**
 * a contract that defines a state machine builder
 * @param  the type of the states
 */
public interface MachineBuilder {
    /**
     * specify a state machine definition. it is mandatory in order to be able to build a state machine.
     *
     * @param definition the state machine definition
     * @return the updated machine builder
     */
    MachineBuilder ofType(MachineDefinition definition);

    /**
     * specify the initial context of the state machine you are building
     *
     * @param context context entries
     * @return the updated machine builder
     */
    MachineBuilder withContext(Map context);

    /**
     * specify an machine ID beforehand. calling this method is optional, it not called a UUID will be generated on the fly
     *
     * @param id  the ID to be used for the machine
     * @return the updated machine builder
     */
    MachineBuilder withId(String id);

    /**
     * configure a set of callbacks to be invoked after each transition - typically to implement persistence or audit trails
     *
     * @param machinePersistenceCallback callbacks to be configured
     * @return the updated machine builder
     */
    MachineBuilder withPersistence(MachinePersistenceCallback machinePersistenceCallback);

    /**
     * build a state machine machine off the specified type and context, and put it in the defined initial state.
     * IF STP transitions are definied out of the initial state, they will be executed.
     *
     * @return a state machine instance
     * @throws TransitionException if transiton imtegrity rules have failed
     */
    Machine build() throws Exception;
}