001/*
002 * JPPF.
003 * Copyright (C) 2005-2018 JPPF Team.
004 * http://www.jppf.org
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019package org.jppf.load.balancer.persistence;
020
021import java.util.List;
022
023/**
024 * This interface must be implemented by services that perform persistence of load-balancers state.
025 * The configuration of an implementation is performed in the JPPF configuration as follows:<br/>
026 * {@code jppf.load.balancing.persistence = <persistence_implementation_class_name> [param1 ... paramN]}
027 * <p>The implementation class must declare either a no-arg constructor or a constructor that takes a {@code String[]} or {@code String...} parameter, or both.
028 * The space-separated optional parameters allow setting up the persistence implementation from the JPPF configuration.
029 * They could be used for instance to specify the root directory for a file-based implementation, or JDBC connection parameters, but are not limited to these.
030 * <p>An implementation that only declares a no-args constructor may still receive parameters if it declares a {@code void setParameters(String...params)} method.
031 * @author Laurent Cohen
032 * @since 6.0
033 */
034public interface LoadBalancerPersistence {
035  /**
036   * Load the state of a load balancer from the persistence sstore.
037   * @param info a {@link LoadBalancerPersistenceInfo} object representing the load balancer and its state.
038   * @return an object representing the load balancer state, or {@code null} if no entry exists in the persistence store for the specified node identifier.
039   * @throws LoadBalancerPersistenceException if any erorr occurs during the persistence operation.
040   */
041  Object load(LoadBalancerPersistenceInfo info) throws LoadBalancerPersistenceException;
042
043  /**
044   * Store a load balancer to the persistence sstore.
045   * @param info a {@link LoadBalancerPersistenceInfo} object representing the load balancer and its state.
046   * @throws LoadBalancerPersistenceException if any erorr occurs during the persistence operation.
047   */
048  void store(LoadBalancerPersistenceInfo info) throws LoadBalancerPersistenceException;
049
050  /**
051   * Delete the specified load-balancer state(s) from the persistence store.
052   * <p>The {@code info} parameter embeds both the scope and identifiers for the artifacts to delete:
053   * <ul>
054   * <li>if {@code info} is {@code null} or both {@code info.getChannelID()} and {@code info.getAlgorithmID()} are {@code null}, then all entries in the persistence store are deleted</li>
055   * <li>if only {@code info.getAlgorithmID()} is {@code null}, then the states of all algorithm for the specified channel are deleted</li>
056   * <li>if only {@code info.getChannelID()} is {@code null}, then the states of the specified algorithm are deleted for all the channels</li>
057   * <li>if neither {@code info.getChannelID()} nor {@code info.getAlgorithmID()} are {@code null}, then only the state of the specified algorithm for the specified channel is deleted</li>
058   * </ul> 
059   * @param info encapsulates information about the artifacts to delete.
060   * @throws LoadBalancerPersistenceException if any erorr occurs during the persistence operation.
061   */
062  void delete(LoadBalancerPersistenceInfo info) throws LoadBalancerPersistenceException;
063  
064  /**
065   * List all entries in the persistence store.
066   * <p>The {@code info} parameter embeds both the scope and identifiers for the artifacts to list:
067   * <ul>
068   * <li>if {@code info} is {@code null} or both {@code info.getChannelID()} and {@code info.getAlgorithmID()} are {@code null}, then all channelIDs in the persistence store are returned</li>
069   * <li>if only {@code info.getAlgorithmID()} is {@code null}, then all the algorithm IDs for the specified channel are returned</li>
070   * <li>if only {@code info.getChannelID()} is {@code null}, then the the IDs of the channels that have a persisted state for the algorithm are returned</li>
071   * <li>if neither {@code info.getChannelID()} nor {@code info.getAlgorithmID()} are {@code null}, then the specified algorithmID is returned (list with a single entry)
072   * if the specified channel has an entry for it, otherwise an empty list must be returned</li>
073   * </ul> 
074   * @param info encapsulates information about the artifacts to delete.
075   * @return a list of nodeIDs or algorithmIDs, depending on the input parameter.
076   * @throws LoadBalancerPersistenceException if any erorr occurs during the persistence operation.
077   */
078  List<String> list(LoadBalancerPersistenceInfo info) throws LoadBalancerPersistenceException;
079}