DemandBalancer.java

/* ==================================================================
 * DemandBalancer.java - Mar 23, 2014 3:58:26 PM
 * 
 * Copyright 2007-2014 SolarNetwork.net Dev Team
 * 
 * This program is free software; you can redistribute it and/or 
 * modify it under the terms of the GNU General Public License as 
 * published by the Free Software Foundation; either version 2 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 Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License 
 * along with this program; if not, write to the Free Software 
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 
 * 02111-1307 USA
 * ==================================================================
 */

package net.solarnetwork.node.control.demandbalancer;

import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.Date;
import java.util.EnumSet;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
import net.solarnetwork.domain.NodeControlInfo;
import net.solarnetwork.node.DatumDataSource;
import net.solarnetwork.node.MultiDatumDataSource;
import net.solarnetwork.node.NodeControlProvider;
import net.solarnetwork.node.domain.ACEnergyDatum;
import net.solarnetwork.node.domain.ACPhase;
import net.solarnetwork.node.domain.EnergyDatum;
import net.solarnetwork.node.reactor.Instruction;
import net.solarnetwork.node.reactor.InstructionHandler;
import net.solarnetwork.node.reactor.InstructionStatus;
import net.solarnetwork.node.reactor.support.BasicInstruction;
import net.solarnetwork.node.reactor.support.InstructionUtils;
import net.solarnetwork.node.settings.KeyedSettingSpecifier;
import net.solarnetwork.node.settings.SettingSpecifier;
import net.solarnetwork.node.settings.SettingSpecifierProvider;
import net.solarnetwork.node.settings.support.BasicTextFieldSettingSpecifier;
import net.solarnetwork.node.settings.support.BasicToggleSettingSpecifier;
import net.solarnetwork.util.FilterableService;
import net.solarnetwork.util.OptionalService;
import net.solarnetwork.util.OptionalServiceCollection;
import net.solarnetwork.util.StaticOptionalService;
import net.solarnetwork.util.StringUtils;
import org.osgi.service.event.Event;
import org.osgi.service.event.EventAdmin;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.MessageSource;

/**
 * Basic service to monitor demand conditions (consumption) and generation
 * (power) and send out {@link InstructionHandler#TOPIC_DEMAND_BALANCE}
 * instructions to a specific control to limit generation to an amount that
 * keeps generation at or below current consumption levels.
 * 
 * <p>
 * The configurable properties of this class are:
 * </p>
 * 
 * <dl class="class-properties">
 * <dt>powerControlId</dt>
 * <dd>The ID of the control that should respond to the
 * {@link InstructionHandler#TOPIC_DEMAND_BALANCE} instruction to match
 * generation levels to consumption levels.</dd>
 * 
 * <dt>powerControl</dt>
 * <dd>The {@link NodeControlProvider} that manages the configured
 * {@code powerControlId}, and can report back its current status, whose value
 * must be provided as an integer percentage of the maximum allowable generation
 * level. <b>Note</b> that this object must also implement
 * {@link FilterableService} and will automatically have a filter property set
 * for the {@code availableControlIds} property to match the
 * {@code powerControlId} value.</dd>
 * 
 * <dt>powerDataSource</dt>
 * <dd>The collection of {@link DatumDataSource} that provide real-time power
 * generation data. If more than one {@code DatumDataSource} is configured the
 * effective generation will be aggregated as a sum total of all of them.</dd>
 * <dt>powerMaximumWatts</dt>
 * 
 * <dd>The maximum watts the configured {@code powerDataSource} is capable of
 * producing. This value is used to calculate the output percentage level passed
 * on {@link InstructionHandler#TOPIC_DEMAND_BALANCE} instructions. For example,
 * if the {@code powerMaximumWatts} is {@bold 1000} and the current
 * consumption is {@bold 800} then the demand balance will be requested
 * as {@bold 80%}.</dd>
 * 
 * <dt>consumptionDataSource</dt>
 * <dd>The collection of {@link DatumDataSource} that provide real-time
 * consumption generation data. If more than one {@code DatumDataSource} is
 * configured the effective demand will be aggregated as a sum total of all of
 * them.</dd>
 * 
 * <dt>balanceStrategy</dt>
 * <dd>The strategy implementation to use to decide how to balance the demand
 * and generation. Defaults to {@link SimpleDemandBalanceStrategy}.</dd>
 * 
 * <dt>instructionHandlers</dt>
 * <dd>A collection of {@link InstructionHandler} instances. When
 * {@link #evaluateBalance()} is called, if a balancing adjustment is necessary
 * then the instruction will be passed to each of these handlers, with the first
 * to process it being assumed the only handler that need respond.</dd>
 * </dl>
 * 
 * <dt>collectPower</dt> <dd>If <em>true</em> then collect {@link PowerDatum}
 * from all configured data sources for passing to the
 * {@link DemandBalanceStrategy}. Not all strategies need power information, and
 * it may take too long to collect this information, however, so this can be
 * turned off by setting to <em>false</em>. When disabled, <b>-1</b> is passed
 * for the {@code generationWatts} parameter on
 * {@link DemandBalanceStrategy#evaluateBalance(String, int, int, int, int)}.
 * Defaults to <em>false</em>.</dd>
 * 
 * @author matt
 * @version 1.2
 */
public class DemandBalancer implements SettingSpecifierProvider {

	private static final String ERROR_NO_DATA_RETURNED = "No data returned.";

	/**
	 * The EventAdmin topic used to post events with statistics on balance
	 * execution.
	 */
	public static final String EVENT_TOPIC_STATISTICS = "net/solarnetwork/node/control/demandbalancer/DemandBalancer/STATISTICS";

	public static final String STAT_LAST_CONSUMPTION_COLLECTION_DATE = "ConsumptionCollectionDate";
	public static final String STAT_LAST_CONSUMPTION_COLLECTION_ERROR = "ConsumptionCollectionError";
	public static final String STAT_LAST_POWER_COLLECTION_DATE = "PowerCollectionDate";
	public static final String STAT_LAST_POWER_COLLECTION_ERROR = "PowerCollectionError";
	public static final String STAT_LAST_POWER_CONTROL_COLLECTION_DATE = "PowerControlCollectionDate";
	public static final String STAT_LAST_POWER_CONTROL_COLLECTION_ERROR = "PowerControlCollectionError";
	public static final String STAT_LAST_POWER_CONTROL_MODIFY_DATE = "PowerControlModifyDate";
	public static final String STAT_LAST_POWER_CONTROL_MODIFY_ERROR = "PowerControlModifyError";

	private String powerControlId = "/power/pcm/1?percent";
	private OptionalService<EventAdmin> eventAdmin;
	private OptionalService<NodeControlProvider> powerControl;
	private OptionalServiceCollection<DatumDataSource<? extends EnergyDatum>> powerDataSource;
	private int powerMaximumWatts = 1000;
	private OptionalServiceCollection<DatumDataSource<? extends EnergyDatum>> consumptionDataSource;
	private OptionalService<DemandBalanceStrategy> balanceStrategy = new StaticOptionalService<DemandBalanceStrategy>(
			new SimpleDemandBalanceStrategy());
	private Collection<InstructionHandler> instructionHandlers = Collections.emptyList();
	private MessageSource messageSource;
	private boolean collectPower = false;
	private Set<ACPhase> acEnergyPhaseFilter = EnumSet.copyOf(Collections.singleton(ACPhase.Total));

	final Map<String, Object> stats = new LinkedHashMap<String, Object>(8);

	private final Logger log = LoggerFactory.getLogger(getClass());

	/**
	 * Evaluate current demand (consumption) and generation (power) and attempt
	 * to maximize power generation up to the current demand level.
	 */
	public void evaluateBalance() {
		final Integer demandWatts = collectDemandWatts();
		final Integer generationWatts = collectGenerationWatts();
		final Integer generationLimitPercent = readCurrentGenerationLimitPercent();
		log.debug("Current demand: {}, generation: {}, capacity: {}, limit: {}",
				(demandWatts == null ? "N/A" : demandWatts.toString()), (generationWatts == null ? "N/A"
						: generationWatts.toString()), powerMaximumWatts,
				(generationLimitPercent == null ? "N/A" : generationLimitPercent + "%"));
		executeDemandBalanceStrategy(demandWatts, generationWatts, generationLimitPercent);
		postStatisticsEvent();
	}

	/**
	 * Get a message for an exception. This will try to return the root cause's
	 * message. If that is not available the name of the root cause's class will
	 * be returned.
	 * 
	 * @param t
	 *        the exception
	 * @return message
	 */
	private String messageForException(Throwable t) {
		Throwable root = t;
		while ( root.getCause() != null ) {
			root = root.getCause();
		}
		String msg = root.getMessage();
		if ( msg == null || msg.length() < 1 ) {
			msg = t.getMessage();
			if ( msg == null || msg.length() < 1 ) {
				msg = root.getClass().getName();
			}
		}
		return msg;
	}

	private Integer collectDemandWatts() {
		log.debug("Collecting current consumption data to inform demand balancer...");
		Iterable<EnergyDatum> demand = null;
		try {
			demand = getCurrentDatum(consumptionDataSource);
			if ( demand.iterator().hasNext() ) {
				stats.put(STAT_LAST_CONSUMPTION_COLLECTION_DATE, System.currentTimeMillis());
				stats.remove(STAT_LAST_CONSUMPTION_COLLECTION_ERROR);
			} else {
				stats.put(STAT_LAST_CONSUMPTION_COLLECTION_ERROR, ERROR_NO_DATA_RETURNED);
			}
		} catch ( RuntimeException e ) {
			log.error("Error collecting consumption data: {}", e.getMessage());
			stats.put(STAT_LAST_CONSUMPTION_COLLECTION_ERROR, messageForException(e));
		}
		return wattsForEnergyDatum(demand);
	}

	private Integer collectGenerationWatts() {
		final Integer generationWatts;
		if ( collectPower ) {
			log.debug("Collecting current generation data to inform demand balancer...");
			Iterable<EnergyDatum> generation = null;
			try {
				generation = getCurrentDatum(powerDataSource);
				if ( generation.iterator().hasNext() ) {
					stats.put(STAT_LAST_POWER_COLLECTION_DATE, System.currentTimeMillis());
					stats.remove(STAT_LAST_POWER_COLLECTION_ERROR);
				} else {
					stats.put(STAT_LAST_POWER_COLLECTION_ERROR, ERROR_NO_DATA_RETURNED);
				}
			} catch ( RuntimeException e ) {
				log.error("Error collecting generation data: {}", e.getMessage());
				stats.put(STAT_LAST_POWER_COLLECTION_ERROR, messageForException(e));
			}
			generationWatts = wattsForEnergyDatum(generation);
		} else {
			generationWatts = null;
		}
		return generationWatts;
	}

	private Integer readCurrentGenerationLimitPercent() {
		log.debug("Reading current {} value to inform demand balancer...", powerControlId);
		NodeControlInfo generationLimit = null;
		try {
			generationLimit = getCurrentControlValue(powerControl, powerControlId);
			if ( generationLimit != null ) {
				stats.put(STAT_LAST_POWER_CONTROL_COLLECTION_DATE, System.currentTimeMillis());
				stats.remove(STAT_LAST_POWER_CONTROL_COLLECTION_ERROR);
			} else {
				stats.put(STAT_LAST_POWER_CONTROL_COLLECTION_ERROR, ERROR_NO_DATA_RETURNED);
			}
		} catch ( RuntimeException e ) {
			log.error("Error collecting {} data: {}", powerControlId, e.getMessage());
			stats.put(STAT_LAST_POWER_CONTROL_COLLECTION_ERROR, messageForException(e));
		}
		return percentForLimit(generationLimit);
	}

	private void executeDemandBalanceStrategy(final Integer demandWatts, final Integer generationWatts,
			final Integer generationLimitPercent) {
		try {
			InstructionStatus.InstructionState result = evaluateBalance((demandWatts == null ? -1
					: demandWatts.intValue()),
					(generationWatts == null ? -1 : generationWatts.intValue()),
					(generationLimitPercent == null ? -1 : generationLimitPercent.intValue()));
			if ( result != null ) {
				stats.put(STAT_LAST_POWER_CONTROL_MODIFY_DATE, System.currentTimeMillis());
			}
			if ( result == null || result == InstructionStatus.InstructionState.Completed ) {
				stats.remove(STAT_LAST_POWER_CONTROL_MODIFY_ERROR);
			} else {
				stats.put(STAT_LAST_POWER_CONTROL_MODIFY_ERROR, "Instruction result not Completed: "
						+ result);
			}
		} catch ( RuntimeException e ) {
			log.error("Error modifying power control {}: {}", powerControlId, e.getMessage());
			stats.put(STAT_LAST_POWER_CONTROL_MODIFY_ERROR, messageForException(e));
		}
	}

	/**
	 * Evaluate current demand and generation conditions, and apply an
	 * adjustment if necessary.
	 * 
	 * @param demandWatts
	 *        the current demand, in watts
	 * @param generationWatts
	 *        the current generation, in watts
	 * @param currentLimit
	 *        the current generation limit, as an integer percentage
	 * @return the result of adjusting the generation limit, or <em>null</em> if
	 *         no adjustment was made
	 */
	private InstructionStatus.InstructionState evaluateBalance(final int demandWatts,
			final int generationWatts, final int currentLimit) {
		DemandBalanceStrategy strategy = getDemandBalanceStrategy();
		if ( strategy == null ) {
			throw new RuntimeException("No DemandBalanceStrategy configured.");
		}
		int desiredLimit = strategy.evaluateBalance(powerControlId, demandWatts, generationWatts,
				powerMaximumWatts, currentLimit);
		if ( desiredLimit > 0 && desiredLimit != currentLimit ) {
			log.info("Demand of {} with generation {} (capacity {}) will be adjusted from {}% to {}%",
					demandWatts, powerControlId, powerMaximumWatts, currentLimit, desiredLimit);
			InstructionStatus.InstructionState result = adjustLimit(desiredLimit);
			log.info("Demand adjumstment instruction result: {}", result);
			return result;
		}
		return null;
	}

	/**
	 * Adjust the generation limit. If no handlers are available, or no handlers
	 * acknowledge handling the instruction,
	 * {@link InstructionStatus.InstructionState#Declined} will be returned.
	 * 
	 * @param desiredLimit
	 *        the desired limit, as an integer percentage
	 * @return the result of handling the adjustment instruction, never
	 *         <em>null</em>
	 */
	private InstructionStatus.InstructionState adjustLimit(final int desiredLimit) {
		final BasicInstruction instr = new BasicInstruction(InstructionHandler.TOPIC_DEMAND_BALANCE,
				new Date(), Instruction.LOCAL_INSTRUCTION_ID, Instruction.LOCAL_INSTRUCTION_ID, null);
		instr.addParameter(powerControlId, String.valueOf(desiredLimit));
		final InstructionStatus.InstructionState result = InstructionUtils.handleInstruction(
				instructionHandlers, instr);
		return (result == null ? InstructionStatus.InstructionState.Declined : result);
	}

	private void postStatisticsEvent() {
		if ( eventAdmin == null ) {
			return;
		}
		final EventAdmin admin = eventAdmin.service();
		if ( admin == null ) {
			return;
		}
		admin.postEvent(new Event(EVENT_TOPIC_STATISTICS, stats));
	}

	private Integer percentForLimit(NodeControlInfo limit) {
		if ( limit == null || limit.getValue() == null ) {
			return null;
		}
		try {
			return Integer.valueOf(limit.getValue());
		} catch ( NumberFormatException e ) {
			log.warn("Error parsing limit value as integer percentage: {}", e.getMessage());
		}
		return null;
	}

	private Integer wattsForEnergyDatum(EnergyDatum datum) {
		if ( datum == null ) {
			return null;
		}
		if ( datum.getWatts() != null ) {
			return datum.getWatts();
		}
		return null;
	}

	private Integer wattsForEnergyDatum(Iterable<? extends EnergyDatum> datums) {
		if ( datums == null ) {
			return null;
		}
		int total = -1;
		for ( EnergyDatum datum : datums ) {
			if ( datum instanceof ACEnergyDatum && acEnergyPhaseFilter != null
					&& acEnergyPhaseFilter.size() > 0 ) {
				ACPhase phase = ((ACEnergyDatum) datum).getPhase();
				if ( !acEnergyPhaseFilter.contains(phase) ) {
					continue;
				}
			}
			Integer w = wattsForEnergyDatum(datum);
			if ( w != null ) {
				if ( total < 0 ) {
					total = w;
				} else {
					total += w;
				}
			}
		}
		return (total < 0 ? null : total);
	}

	private NodeControlInfo getCurrentControlValue(OptionalService<NodeControlProvider> service,
			String controlId) {
		if ( service == null ) {
			return null;
		}
		NodeControlProvider provider = service.service();
		if ( provider == null ) {
			return null;
		}
		return provider.getCurrentControlInfo(controlId);
	}

	private Iterable<EnergyDatum> getCurrentDatum(
			OptionalServiceCollection<DatumDataSource<? extends EnergyDatum>> service) {
		if ( service == null ) {
			return null;
		}
		Iterable<DatumDataSource<? extends EnergyDatum>> dataSources = service.services();
		List<EnergyDatum> results = new ArrayList<EnergyDatum>();
		for ( DatumDataSource<? extends EnergyDatum> dataSource : dataSources ) {
			if ( dataSource instanceof MultiDatumDataSource<?> ) {
				@SuppressWarnings("unchecked")
				Collection<? extends EnergyDatum> datums = ((MultiDatumDataSource<? extends EnergyDatum>) dataSource)
						.readMultipleDatum();
				if ( datums != null ) {
					for ( EnergyDatum datum : datums ) {
						results.add(datum);
					}
				}
			} else {
				EnergyDatum datum = dataSource.readCurrentDatum();
				if ( datum != null ) {
					results.add(datum);
				}
			}
		}
		return results;
	}

	private DemandBalanceStrategy getDemandBalanceStrategy() {
		if ( balanceStrategy == null ) {
			return null;
		}
		return balanceStrategy.service();
	}

	/**
	 * Getter for the current {@link DemandBalanceStrategy}.
	 * 
	 * @return the strategy
	 */
	public DemandBalanceStrategy getStrategy() {
		return getDemandBalanceStrategy();
	}

	// SettingSpecifierProvider

	@Override
	public String getSettingUID() {
		return "net.solarnetwork.node.control.demandbalancer";
	}

	@Override
	public String getDisplayName() {
		return "Demand Balancer";
	}

	@Override
	public MessageSource getMessageSource() {
		return messageSource;
	}

	@Override
	public List<SettingSpecifier> getSettingSpecifiers() {
		DemandBalancer defaults = new DemandBalancer();
		List<SettingSpecifier> results = new ArrayList<SettingSpecifier>(6);
		results.add(new BasicTextFieldSettingSpecifier("balanceStrategy.propertyFilters['UID']",
				"Default"));
		results.add(new BasicTextFieldSettingSpecifier("consumptionDataSource.propertyFilters['UID']",
				"Main"));
		results.add(new BasicTextFieldSettingSpecifier(
				"consumptionDataSource.propertyFilters['groupUID']", ""));
		results.add(new BasicTextFieldSettingSpecifier("acEnergyPhaseFilter", defaults
				.getAcEnergyPhaseFilterValue()));
		results.add(new BasicToggleSettingSpecifier("collectPower", defaults.isCollectPower()));
		results.add(new BasicTextFieldSettingSpecifier("powerDataSource.propertyFilters['UID']", "Main"));
		results.add(new BasicTextFieldSettingSpecifier("powerDataSource.propertyFilters['groupUID']", ""));
		results.add(new BasicTextFieldSettingSpecifier("powerControlId", defaults.powerControlId));
		results.add(new BasicTextFieldSettingSpecifier("powerMaximumWatts", String
				.valueOf(defaults.powerMaximumWatts)));

		DemandBalanceStrategy strategy = getDemandBalanceStrategy();
		if ( strategy instanceof SettingSpecifierProvider ) {
			SettingSpecifierProvider stratSettingProvider = (SettingSpecifierProvider) strategy;
			List<SettingSpecifier> strategySpecifiers = stratSettingProvider.getSettingSpecifiers();
			if ( strategySpecifiers != null && strategySpecifiers.size() > 0 ) {
				for ( SettingSpecifier spec : strategySpecifiers ) {
					if ( spec instanceof KeyedSettingSpecifier<?> ) {
						KeyedSettingSpecifier<?> keyedSpec = (KeyedSettingSpecifier<?>) spec;
						results.add(keyedSpec.mappedTo("strategy."));
					} else {
						results.add(spec);
					}
				}
			}
		}

		return results;
	}

	// Accessors

	public void setPowerControlId(String powerControlId) {
		this.powerControlId = powerControlId;
		if ( this.powerControl != null ) {
			// automatically enforce filter
			((FilterableService) this.powerControl).setPropertyFilter("availableControlIds",
					this.powerControlId);
		}
	}

	public void setPowerControl(OptionalService<NodeControlProvider> powerControl) {
		if ( !(powerControl instanceof FilterableService) ) {
			throw new IllegalArgumentException("OptionalService must also implement "
					+ FilterableService.class.getName());
		}
		((FilterableService) powerControl).setPropertyFilter("availableControlIds", this.powerControlId);
		this.powerControl = powerControl;

	}

	public void setPowerDataSource(
			OptionalServiceCollection<DatumDataSource<? extends EnergyDatum>> powerDataSource) {
		this.powerDataSource = powerDataSource;
	}

	public void setPowerMaximumWatts(int powerMaximumWatts) {
		this.powerMaximumWatts = powerMaximumWatts;
	}

	public void setConsumptionDataSource(
			OptionalServiceCollection<DatumDataSource<? extends EnergyDatum>> consumptionDataSource) {
		this.consumptionDataSource = consumptionDataSource;
	}

	public void setBalanceStrategy(OptionalService<DemandBalanceStrategy> balanceStrategy) {
		this.balanceStrategy = balanceStrategy;
	}

	public void setInstructionHandlers(Collection<InstructionHandler> instructionHandlers) {
		this.instructionHandlers = instructionHandlers;
	}

	public void setMessageSource(MessageSource messageSource) {
		this.messageSource = messageSource;
	}

	public String getPowerControlId() {
		return powerControlId;
	}

	public OptionalService<NodeControlProvider> getPowerControl() {
		return powerControl;
	}

	public OptionalServiceCollection<DatumDataSource<? extends EnergyDatum>> getPowerDataSource() {
		return powerDataSource;
	}

	public int getPowerMaximumWatts() {
		return powerMaximumWatts;
	}

	public OptionalServiceCollection<DatumDataSource<? extends EnergyDatum>> getConsumptionDataSource() {
		return consumptionDataSource;
	}

	public OptionalService<DemandBalanceStrategy> getBalanceStrategy() {
		return balanceStrategy;
	}

	public Collection<InstructionHandler> getInstructionHandlers() {
		return instructionHandlers;
	}

	public boolean isCollectPower() {
		return collectPower;
	}

	public void setCollectPower(boolean collectPower) {
		this.collectPower = collectPower;
	}

	public OptionalService<EventAdmin> getEventAdmin() {
		return eventAdmin;
	}

	public void setEventAdmin(OptionalService<EventAdmin> eventAdmin) {
		this.eventAdmin = eventAdmin;
	}

	public Set<ACPhase> getAcEnergyPhaseFilter() {
		return acEnergyPhaseFilter;
	}

	public void setAcEnergyPhaseFilter(Set<ACPhase> acEnergyPhaseFilter) {
		this.acEnergyPhaseFilter = acEnergyPhaseFilter;
	}

	/**
	 * Get the value of the {@code acEnergyPhaseFilter} property as a
	 * comma-delimited string.
	 * 
	 * @return the AC phase as a delimited string
	 */
	public String getAcEnergyPhaseFilterValue() {
		return (acEnergyPhaseFilter == null ? null : StringUtils
				.commaDelimitedStringFromCollection(acEnergyPhaseFilter));
	}

	/**
	 * Set the {@code acEnergyPhaseFilter} property via a comma-delimited
	 * string.
	 * 
	 * @param value
	 *        the comma delimited string
	 * @see #getAcEnergyTotalPhaseOnlyPropertiesValue()
	 */
	public void getAcEnergyPhaseFilterValue(String value) {
		Set<String> set = StringUtils.commaDelimitedStringToSet(value);
		if ( set == null ) {
			acEnergyPhaseFilter = null;
			return;
		}
		Set<ACPhase> result = new LinkedHashSet<ACPhase>(set.size());
		for ( String phase : set ) {
			try {
				ACPhase p = ACPhase.valueOf(phase);
				result.add(p);
			} catch ( IllegalArgumentException e ) {
				log.warn("Ignoring unsupported ACPhase value [{}]", phase);
			}
		}
		acEnergyPhaseFilter = EnumSet.copyOf(result);
	}

}