001package org.cpsolver.ifs.assignment.context; 002 003import org.cpsolver.ifs.assignment.Assignment; 004import org.cpsolver.ifs.criteria.AbstractCriterion; 005import org.cpsolver.ifs.model.Model; 006import org.cpsolver.ifs.model.Value; 007import org.cpsolver.ifs.model.Variable; 008 009/** 010 * An interface to be implemented by a class that need an assignment context associated with it. 011 * I.e., for each existing assignment, there can be an instance of {@link AssignmentContext} available 012 * to the class.<br><br> 013 * 014 * The idea is that each class that needs to keep some assignment dependent data will implements 015 * {@link HasAssignmentContext} interface and the data will be wrapped by this class. 016 * The {@link HasAssignmentContext} will only contain a reference to this 017 * assignment context, created by calling {@link Model#createReference(HasAssignmentContext)} 018 * during its initialization. The assignment context can be than accessed by calling 019 * {@link Assignment#getAssignmentContext(AssignmentContextReference)}.<br><br> 020 * 021 * These assignment contexts are being held in memory by a class implementing the 022 * {@link AssignmentContextHolder} interface. For constraints, criteria, extensions, and 023 * neighborhood selections an existing class implementing the context can be used, see 024 * {@link ConstraintWithContext}, {@link AbstractCriterion}, {@link ExtensionWithContext}, 025 * and {@link NeighbourSelectionWithContext} respectively.<br><br> 026 * 027 * For instance, when implementing {@link ConstraintWithContext}, only the method 028 * {@link ConstraintWithContext#createAssignmentContext(Assignment)} needs to be implemented and the 029 * assignment context can be accessed within the constraint using the method 030 * {@link ConstraintWithContext#getContext(Assignment)}. 031 * 032 * @see AssignmentContextHolder 033 * @see HasAssignmentContext 034 * 035 * @version IFS 1.3 (Iterative Forward Search)<br> 036 * Copyright (C) 2014 Tomáš Müller<br> 037 * <a href="mailto:muller@unitime.org">muller@unitime.org</a><br> 038 * <a href="http://muller.unitime.org">http://muller.unitime.org</a><br> 039 * <br> 040 * This library is free software; you can redistribute it and/or modify 041 * it under the terms of the GNU Lesser General Public License as 042 * published by the Free Software Foundation; either version 3 of the 043 * License, or (at your option) any later version. <br> 044 * <br> 045 * This library is distributed in the hope that it will be useful, but 046 * WITHOUT ANY WARRANTY; without even the implied warranty of 047 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 048 * Lesser General Public License for more details. <br> 049 * <br> 050 * You should have received a copy of the GNU Lesser General Public 051 * License along with this library; if not see <a href='http://www.gnu.org/licenses'>http://www.gnu.org/licenses</a>. 052 * @param <V> Variable 053 * @param <T> Value 054 * @param <C> Assignment Context 055 **/ 056public interface HasAssignmentContext <V extends Variable<V, T>, T extends Value<V, T>, C extends AssignmentContext> { 057 058 /** 059 * Create a new assignment context for the given assignment. If there are already some variables assigned in 060 * the value, the method should make sure that the context is appropriately initialized. 061 * @param assignment an assignment for which there needs to be an assignment context 062 * @return a new instance of the assignment context, filled according to the given assignment 063 */ 064 public C createAssignmentContext(Assignment<V,T> assignment); 065 066 /** 067 * Returns an assignment context reference 068 * @return reference provided by the model by calling {@link Model#createReference(HasAssignmentContext)} during initialization 069 */ 070 public AssignmentContextReference<V, T, C> getAssignmentContextReference(); 071 072 /** 073 * Store an assignment context reference that was given for the class by the {@link Model#createReference(HasAssignmentContext)}. 074 * @param reference reference provided by the model by calling {@link Model#createReference(HasAssignmentContext)} during initialization 075 */ 076 public void setAssignmentContextReference(AssignmentContextReference<V, T, C> reference); 077 078 /** 079 * Returns an assignment context associated with this object. If there is no 080 * assignment context associated with this object yet, one is created using the 081 * {@link ConstraintWithContext#createAssignmentContext(Assignment)} method. 082 * @param assignment given assignment 083 * @return assignment context associated with this object and the given assignment 084 */ 085 public C getContext(Assignment<V, T> assignment); 086}