Package com.dna.jopt.framework.body

Interface IOptimization

All Superinterfaces:
IOptimizationEventListener
All Known Implementing Classes:
Optimization
public interface IOptimization extends IOptimizationEventListener
The interface IOptimization is the framework for the optimization run and provides methods to set the license, properties, the scheme, adding elements and start the run (sync. or async.).
Since:
29/07/2018
Version:
14/10/2019
Author:
DNA

  • Method Details

    • proceed

      void proceed()
      Checks that Optimization.getCurrentOptimizationAlgo() is not null, then calls IOptimizationAlgorithm.proceed() which wakes up all threads that are waiting on this object's monitor.
      See Also:

    • pause

      void pause()
      Checks that Optimization.getCurrentOptimizationAlgo() is not null, then calls IOptimizationAlgorithm.pause().
      See Also:

    • stopOptimization

      void stopOptimization()
      Checks that Optimization.getCurrentOptimizationAlgo() is not null, then sets Optimization.isStopOptimization() to true and calls IOptimizationAlgorithm.jumpToEnd(). This call will trigger a graceful optimization stop triggering the optimization result.

    • jumpToNextStage

      void jumpToNextStage()
      Checks that Optimization.getCurrentOptimizationAlgo() is not null, then calls IOptimizationAlgorithm.jumpToEnd().

    • requestResult

      void requestResult()
      Requesting an intermediate IOptimizationResult result which will be provided in an async. manner.

      Checks that Optimization.getCurrentOptimizationAlgo() is not null, then calls IOptimizationAlgorithm.requestResult().

    • requestedAsynchronousOptimizationResult

      void requestedAsynchronousOptimizationResult(IOptimizationResult result)
      Requested asynchronous optimization result.
      Specified by:
      requestedAsynchronousOptimizationResult in interface IOptimizationEventListener
      Parameters:
      result - the result to print

    • setInitialEntity

      void setInitialEntity(IEntity initialEntity)
      Sets the initial IEntity as the workEntity and Optimization.hasEntitySetByUser() to true. This method is used to load custom solutions and is used during the loading of a snapshot.

      Will throw an IllegalStateException if the initial entity is null.

      Parameters:
      initialEntity - the new initial entity

    • setInitialEntity

      void setInitialEntity(IEntity initialEntity, boolean reassignUnassignedNode)
      Sets the given IEntity as the initial Entity.
      Parameters:
      initialEntity - the entity to be set
      reassignUnassignedNode - the reassign unassigned node

    • setThreadPrefix

      void setThreadPrefix(String threadPrefix)
      Sets the Optimization.getThreadPrefix() , the default value is "JOPT-". This helps to identify the running optimization thread on the user system.
      Parameters:
      threadPrefix - the prefix to be set

    • getPropertyProvider

      com.dna.jopt.framework.inputplausibility.properties.IPropertyProvider getPropertyProvider()
      Gets the property provider through IOptimizationSetup.getPropertyProvider().
      Returns:
      the propertyProvider

    • setNodeConnector

      void setNodeConnector(INodeEdgeConnector nodeConnector)
      Sets the Optimization.getNodeConnector().

      Cannot be null.

      Parameters:
      nodeConnector - the new node connector

    • getNodeConnector

      INodeEdgeConnector getNodeConnector()
      Gets the Optimization.getNodeConnector().
      Returns:
      the node connector

    • addElement

      void addElement(INode node)
      Adds an INode to the optimization.
      Parameters:
      node - the element to be added.

    • addElement

      void addElement(IResource res)
      Adds an IResource to the optimization.
      Parameters:
      res - the resource

    • addElement

      void addElement(Properties properties)
      Sets the given properties as Optimization.getUserProperties() and invokes the user properties.

      A list of all properties can be generated by the following code example: 

      
   public static void printJOptProperties() {

 List<String> categories = new ArrayList<>();
 categories.add("CATEGORY_MISC");
 categories.add("CATEGORY_SYSTEM");
 categories.add("CATEGORY_OPTIMIZATION_GENERAL_SETUP");
 categories.add("CATEGORY_OPTIMIZATION_CONSTRUCTION");
 categories.add("CATEGORY_OPTIMIZATION_PRE_OPTIMIZATION_SETUP");
 categories.add("CATEGORY_OPTIMIZATION_GENETIC_SETUP");
 categories.add("CATEGORY_OPTIMIZATION_2OPT");
 categories.add("CATEGORY_OPTIMIZATION_WEIGHTS");
 categories.add("CATEGORY_OPTIMIZATION_AUTOFILTER");
 categories.add("CATEGORY_OPTIMIZATION_CO_SETUP");
 categories.add("CATEGORY_OPTIMIZATION_DEPRECATED");

 IOptimization myDummyOptimization =  new Optimization();

 // Read out current properties
 List<PropertyItem> categorySortedPropItems =
 myDummyOptimization.getPropertyProvider()
 .getPropertyItems()
 .stream()
 .sorted((o1,o2)->Integer.compare(o1.getCategoryIdent(), o2.getCategoryIdent()))
 .collect(Collectors.toList());

 categorySortedPropItems
 .stream()
 .forEach(
 i -> {
 if (i.getCategoryIdent() == PropertyItem.CATEGORY_OPTIMIZATION_DEPRECATED) {
 System.out.print("\n-== DEPRECATED PROPERTY ==-");
 } else {
 System.out.print("\n");
 }

 System.out.print(
 "\nCategory: "
 + categories.get(i.getCategoryIdent())
 + "\nDescription: "
 + i.getDescription()
 + "\nDefault Key: "
 + i.getValidatedPropertyName()
 + "\nDefault Value: "
 + i.getDefaultValue()
 + "\nAllowed Values: "
 + i.getAllowedValues()
 + "\n");
 });
 }
      Parameters:
      properties - the properties

    • setLicenceKey

      @Deprecated void setLicenceKey(String key)
      Deprecated.
      please use setLicense(ObjectInputStream), setLicense(File) or setLicense(IRapotLicense) instead.
      Sets the licence key.
      Parameters:
      key - the string new licence key

    • setLicense

      @Deprecated void setLicense(com.dna.jopt.framework.licensing.IRapotLicense key)
      Deprecated.
      Sets the license key loaded from a file and already read in license object.
      Parameters:
      key - the iRapotLicense new license

    • setLicense

      @Deprecated void setLicense(ObjectInputStream licensestream)
      Deprecated.
      Sets the license key via an input stream.

      The following code example can be used to read in a file from a resource folder: 

      
 public class ExampleLicenseHelper {

 private static final String LICNCES_PATH = "src/test/resources/myKeyFile.dli";

 private ExampleLicenseHelper() {
 // Nothing to do
 }

 public static boolean setLicense(IOptimization opti) {
 try {
 ObjectInputStream ois =
 new ObjectInputStream(new FileInputStream(new File(ExampleLicenseHelper.LICNCES_PATH)));
 opti.setLicense(ois);

 return true;

 } catch (IOException e) {
 e.printStackTrace();
 return false;
 }
 }
 }
      Parameters:
      licensestream - the objectinputstream

    • setLicense

      @Deprecated void setLicense(File file) throws IOException
      Deprecated.
      Sets the license key via a file object.
      Parameters:
      file - the key
      Throws:
      IOException - the io exception

    • addElement

      void addElement(IPillarNode pillarnode)
      Adds a IPillarNode to the optimization.
      Parameters:
      pillarnode - the pillarnode to be added

    • setOptimizationScheme

      void setOptimizationScheme(IOptimizationScheme optimizationScheme)
      Sets the IOptimizationScheme.
      Parameters:
      optimizationScheme - the iOptimizationscheme to add

    • getCurrentOptimizationAlgo

      com.dna.jopt.revision.algorithm.IOptimizationAlgorithm getCurrentOptimizationAlgo()
      Calls OptimizationSubController.getCurrentOptimizationAlgo(). Returns the currently running optimization algorithm.
      Returns:
      the current optimizationalgorithm

    • getOptimizationScheme

      IOptimizationScheme getOptimizationScheme()
      Gets the defined IOptimizationScheme.
      Returns:
      the optimizationscheme

    • settleOptimization

      void settleOptimization()
      Internally called to settle the optimization, e.g. finishing all running postStepManagers.

    • getUnassignNodeManager

      INodeUnassigner getUnassignNodeManager()
      Gets the INodeUnassigner of the optimization.
      Returns:
      the unassignNodeManager

    • setUnassignNodeManager

      void setUnassignNodeManager(INodeUnassigner unassignNodeManager)
      Sets the INodeUnassigner.

      Cannot be null.

      Parameters:
      unassignNodeManager - the unassign node manager

    • startAsynchronousOptimizationRun

      @Deprecated void startAsynchronousOptimizationRun() throws InvalidLicenceException
      Deprecated.
      Start asynchronous optimization run.
      Calls startRunSync(long, TimeUnit) with MAX_VALUE as long and MILLISECONDS as TimeUnit.
      Throws:
      InvalidLicenceException - the invalid licence exception

    • getVersion

      String getVersion()
      Gets information about the build of the library.
      Returns:
      the string myVersion

    • addDistanceMatrix

      @Deprecated void addDistanceMatrix(double[][] distanceMatrix)
      Deprecated.
      Adding distance as a INodeConnectorItem is preferred.
      Sets a distance matrix. Later on this information will be used to create a NodeEdgeConnector. This method acts as a wrapper.
      Parameters:
      distanceMatrix - the double array distance matrix
      Category:
      Legacy

    • addTimeMatrix

      @Deprecated void addTimeMatrix(double[][] timeMatrix)
      Deprecated.
      Adding time as a INodeConnectorItem is preferred.
      Sets a time matrix. Later on this information will be used to create a NodeEdgeConnector. This method acts as a wrapper.s.
      Parameters:
      timeMatrix - the double array time matrix
      Category:
      Legacy

    • getOptimizationStage

      int getOptimizationStage()
      Calls OptimizationSubController.getCurrentOptimizationAlgo(). For example, in case three optimization algorithms and currently the second algorithm is running the stage identifier is one. The first algorithm would have the stage identifier zero.
      Returns:
      returns the optimizationAlgo

    • getThreadPrefix

      String getThreadPrefix()
      Gets the Optimization.threadPrefix, the standard value is "JOPT-".
      Returns:
      the string threadPrefix

    • getOptimizationSetup

      com.dna.jopt.framework.body.setup.IOptimizationSetup getOptimizationSetup()
      Gets the IOptimizationSetup.
      Returns:
      the optimizationSetup

    • isStopOptimization

      boolean isStopOptimization()
      Used internally to keep track if the optimization is stopped.
      Returns:
      the boolean optimizationWasStopped

    • getWorkEntity

      IEntity getWorkEntity()
      Gets the Optimization.workEntity.
      Returns:
      the iEntity workEntity

    • setWorkEntity

      void setWorkEntity(IEntity currentBestEntity)
      Sets the Optimization.workEntity.
      Parameters:
      currentBestEntity - the workEntity to be set

    • getAllElements

      List<IOptimizationElement> getAllElements()
      Calls IEntity.getAllEntityElements() and INodeUnassigner.getUnassignedNodes() , then returns all of these elements. Returns a new Arraylist if these are null.
      Returns:
      the List<IOptimizationElement> with all the elements

    • getNoneOptimizableElements

      List<IOptimizationElement> getNoneOptimizableElements()
      Calls IEntity.getNoneOptimizableElements() if Optimization.getWorkEntity() is not null. Otherwise returns a new Arraylist.
      Returns:
      a List<IOptimizationElement>

    • getOptimizableElements

      List<IOptimizationElement> getOptimizableElements()
      Calls IEntity.getNoneOptimizableElements() if the getWorkEntity() is not null. Otherwise returns a new Arraylist.
      Returns:
      the List<IOptimizationElement>

    • getAllRoutesElements

      List<IOptimizationElement> getAllRoutesElements(String resourceId)
      Calls IEntity.getAllRoutesElements(String), if getWorkEntity() is not null.

      If the route of the given resource does not have any elements returns a new ArrayList<>.

      Parameters:
      resourceId - the string resourceId
      Returns:
      the ArrayList<> of the route elements

    • getNoneOptimizableElementsDetails

      Map<String,ILogicRouteElementDetailItem> getNoneOptimizableElementsDetails()
      Gets the Optimization.getNoneOptimizableElementsDetailHolder().
      Returns:
      none optimizable elements details

    • getNoneOptimizableNodDetail

      ILogicRouteElementDetailItem getNoneOptimizableNodDetail(String elementId)
      Gets the value in the Optimization.getNoneOptimizableElementsDetailHolder() for the given elementId. This method is primarily used for internal purpose. Please try to extract details from the route itself.
      Parameters:
      elementId - the string key for the value
      Returns:
      the value of the elementId in noneOptimizableElementsDetailHolder

    • putNoneOptimizableNodDetail

      void putNoneOptimizableNodDetail(String elementId, ILogicRouteElementDetailItem details)
      Puts a value at elementId in Optimization.getNoneOptimizableElementsDetailHolder().
      Parameters:
      elementId - the string id for the value to be put
      details - the iLogicRouteElementDetailItem that is supposed to be put

    • addNodes

      void addNodes(List<INode> nodes)
      Adds all nodes in the list to the optimization.
      Parameters:
      nodes - the list<INode> of nodes to be added

    • addResources

      void addResources(List<IResource> resources)
      Adds all resources in the list to the optimization.
      Parameters:
      resources - the list<IResource> to be added

    • hasEntitySetByUser

      boolean hasEntitySetByUser()
      Checks Optimization.hasEntitySetByUser(), the default value is false.
      Returns:
      the boolean hasUserEntity

    • getId

      long getId()
      Gets the id of the current thread.
      Returns:
      the long thread id
      See Also:

    • getOptimizationEvents

      OptimizationEvents getOptimizationEvents()
      Gets the OptimizationEvents which are backed by multiple ReplaySubject and CompletableFuture. OptimizationEvents can be used to subscribe to different events of the optimization.
      Returns:
      the optimizationevents

    • setOptimizationAlgorithmStart

      void setOptimizationAlgorithmStart(com.dna.jopt.revision.algorithm.IOptimizationAlgorithm.OptimizationAlgorithmStart modeSA, com.dna.jopt.revision.algorithm.IOptimizationAlgorithm.OptimizationAlgorithmStart modeGE)
      Sets the Optimization.initialOptimizationModeGE and Optimization.initialOptimizationModeSA, both have the default value STATE_MODE_BATCH.
      Parameters:
      modeSA - the modeSA
      modeGE - the modeGE

    • startRunSync

      IOptimizationResult startRunSync(long timeout, TimeUnit unit) throws InvalidLicenceException, InterruptedException, ExecutionException, TimeoutException
      Start run sync. internally creates a completable future. The optimization is started within a ForkJoinPool. Internally get() is called on it so that the code will block until the completable future returns. However, as the run is outsourced into multiple threads the Optimization object itself stays responsive to allow for example to request an intermediate optimization result.

      The timeout sets the time within which the completable future needs to return, otherwise a TimeoutException is thrown

      For use without a timeout please use startRunAsync()

      Parameters:
      timeout - the long number of the to be defined time unit until timeout
      unit - the timeUnit of the timeout
      Returns:
      the ioptimization result
      Throws:
      InvalidLicenceException - the invalid licence exception
      InterruptedException - the interrupted exception
      ExecutionException - the execution exception
      TimeoutException - the timeout exception if the completable future has not been done within the timeout

    • startRunAsync

      CompletableFuture<IOptimizationResult> startRunAsync() throws InvalidLicenceException
      Start run async. creates a completable future which is returned.
      Returns:
      completable future
      Throws:
      InvalidLicenceException - the invalid licence exception

    • setInitialEntityRenewAutoFilterControllers

      void setInitialEntityRenewAutoFilterControllers(IEntity initialEntity)
      Sets Optimization.hasEntitySetByUser() and tryRenewAutoFilterController to true, then sets the input initialEntity as the Optimization.getWorkEntity().
      Parameters:
      initialEntity - the iEntity to be set as workEntity

    • setAutoFilterExecutionSchedule

      void setAutoFilterExecutionSchedule(List<Double> executionList)
      Sets hasUserAutoFilterExectuionList to true, then sets the input as the userExecutionList.
      Parameters:
      executionList - the List<Double> to be set as userExecutionList

    • getUserProperties

      Optional<Properties> getUserProperties()
      Gets the Optimization.getUserProperties(), if null returns empty().
      Returns:
      the userProperties

    • cleanUpOptimization

      boolean cleanUpOptimization()
      Clean up optimization boolean. Returns true.
      Returns:
      true

    • cleanUpNoneOptimizableElementsDetailHolder

      void cleanUpNoneOptimizableElementsDetailHolder(Set<String> deadIds)
      Clean up none optimizable elements detail holder.
      Parameters:
      deadIds - the dead ids

    • getCoreVersionProperties

      Properties getCoreVersionProperties()
      Gets the OptimizationVersionHelper.getCoreVersionProperties() of myVersionHelper.
      Returns:
      the versionCoreProperties

    • getCoreVersion

      String getCoreVersion()
      Gets the OptimizationVersionHelper.getCoreVersionProperties() of myVersionHelper.
      Returns:
      the versionCoreProperties

    • setUserEntityCoreBuildOptions

      void setUserEntityCoreBuildOptions(Properties userEntityCoreBuildOptions)
      Sets Optimization.userEntityCoreBuildOptionsOpt as an Optional with the parameter values if not null. Will set it as an empty Optional if null.
      Parameters:
      userEntityCoreBuildOptions - the optional with the given parameters

    • getUserEntityCoreBuildOptions

      Optional<Properties> getUserEntityCoreBuildOptions()
      Gets the Optimization.userEntityCoreBuildOptionsOpt. The default value is an empty Optional.
      Returns:
      the optional userEntityCoreBuildOptionsOpt

    • getFirstMatchingRoute

      Optional<ILogicEntityRoute> getFirstMatchingRoute(String nodeId)
      Invokes IEntity.getFirstMatchingRoute(String) if Optimization.workEntity is not null.
      Parameters:
      nodeId - the string of the nodeId that is supposed to match
      Returns:
      an optional with the matching route or an empty optional

    • getFirstMatchingRoute

      Optional<ILogicEntityRoute> getFirstMatchingRoute(INode node)
      Invokes IEntity.getFirstMatchingRoute(INode) if Optimization.workEntity is not null.
      Parameters:
      node - the iNode that is supposed to match
      Returns:
      an optional with the matching route or an empty optional

    • getAnchoredRoutes

      List<ILogicEntityRoute> getAnchoredRoutes()
      Invokes IEntity.getAnchoredRoutes() if Optimization.workEntity is not null. Otherwise returns a new ArrayList.
      Returns:
      the anchored routes

    • addReassignNodes

      void addReassignNodes(List<INode> nodes)
      Adds reassign nodes. In case a custom solution is used setInitialEntity(com.dna.jopt.member.bucket.entity.IEntity), or the optimization is resumed from a snapshot additional nodes can be added. In contrast to addElement(com.dna.jopt.member.unit.node.INode), nodes are put in an optimized fashion into the existing solution.

      If no solution by the user is provided, calling this method has the same effect as addElement(com.dna.jopt.member.unit.node.INode).

      Parameters:
      nodes - the nodes

    • addReassignResources

      void addReassignResources(List<IResource> ress)
      Adds reassign resources. In case a custom solution is used setInitialEntity(com.dna.jopt.member.bucket.entity.IEntity), or the optimization is resumed from a snapshot additional resources can be added.

      If no solution by the user is provided, calling this method has the same effect as addElement(com.dna.jopt.member.unit.node.INode).

      Parameters:
      ress - the resources

    • startRunAsync

      @Deprecated CompletableFuture<IOptimizationResult> startRunAsync(ObjectInputStream license) throws InvalidLicenceException
      Deprecated.
      Start run async by providing an additional license stream.
      Parameters:
      license - the license
      Returns:
      the completable future
      Throws:
      InvalidLicenceException - the invalid licence exception
      See Also:

    • setLicenseJSON

      void setLicenseJSON(String jsonLic)

    • setLicenseJSON

      void setLicenseJSON(File file) throws IOException
      Throws:
      IOException

    • getReassignNodes

      List<INode> getReassignNodes()

    • getReassignResources

      List<IResource> getReassignResources()

    • requestProgress

      void requestProgress()
      Requesting a IOptimizationProgress progress which will be provided in an async. manner.

      Checks that Optimization.getCurrentOptimizationAlgo() is not null, then calls IOptimizationAlgorithm.requestProgress().

    • requestExportState

      void requestExportState(OutputStream output, String executionId)
      Request export state with 100 Days of internal timeOut. The optimization will be saved as JSON to the provided outputStream. Further, when the saving is done, to returned CompletableFuture is completed with the provided executionId.
      Parameters:
      output - the output
      executionId - the execution id

    • requestExportState

      void requestExportState(OutputStream output, String executionId, Duration timeOut) throws TimeoutException
      Request export state with time out. The optimization will be saved as JSON to the provided outputStream. Further, when the saving is done, to returned CompletableFuture is completed with the provided executionId.
      Parameters:
      output - the output
      executionId - the execution id
      timeOut - the time out
      Throws:
      TimeoutException - the timeout exception

    • resetInitialEntity

      void resetInitialEntity()
      Reset initial entity. This method will reset an entity that was assigned to the optimization. It is only allowed to reset an entity before the optimization is started.

      This methods helps to use an existing solution to be used only as data provider, ignoring an existing solution.

    • getOptimizationElement

      Optional<IOptimizationElement> getOptimizationElement(String id)
      Gets the optimization element. Extracts an element (Resource or Node) that is member of any route of the current optimization run. Unassigned elements are not found.
      Parameters:
      id - the id
      Returns:
      the optimization element

    • getOptimizationElement

      Optional<IOptimizationElement> getOptimizationElement(String id, boolean includeUnassignedElements)
      Gets the optimization element. Extracts an element (Resource or Node) that is member of any route of the current optimization run. Unassigned elements can be found if includeUnassignedElements is true.
      Parameters:
      id - the id
      includeUnassignedElements - the include unassigned elements
      Returns:
      the optimization element

    • getUnassignedElement

      Optional<IOptimizationElement> getUnassignedElement(String id)
      Gets an unassigned element if present.
      Parameters:
      id - the id
      Returns:
      the unassigned element

    • setOptimizationRunIdent

      boolean setOptimizationRunIdent(String ident)
      Sets the optimization run identification string. This can be an arbitrary user provided String to identify a run. If no ident is provided, the Optimizer will generate an ident whenever the optimization is saved.
      Parameters:
      ident - the ident
      Returns:
      true, if accepted

    • getOptimizationRunIdent

      String getOptimizationRunIdent()
      Gets the optimization run ident. If no ident was provided the Optimizer creates an ident on the first call of this method.
      Returns:
      the optimization run ident

    • setOptimizationCreator

      boolean setOptimizationCreator(String creator)

    • getOptimizationCreator

      Optional<String> getOptimizationCreator()

    • handleOnErrorInterruptionState

      void handleOnErrorInterruptionState(Throwable e)
      Handle on error interruption state after throwable in preparation state
      Parameters:
      e - the e