Merge pull request #2 from vlkong/master

Added new sample showing how to use JdbcCustomDataSource in .dat

Author: vlkong

.gitignore

@@ -2,7 +2,6 @@
 # bin dirs
 bin/
 build/
-lib/
 
 # This is not distributed, but contain libs for local deps management
 external_libs/

README.md

@@ -6,18 +6,21 @@ OPL custom data source API to import data from a JDBC data source into an OPL mo
 This sample illustrates the [Subclassing IloCustomOplDataSoource](https://www.ibm.com/support/knowledgecenter/en/SSSA5P_12.8.0/ilog.odms.ide.help/OPL_Studio/opllanguser/topics/opl_languser_extfunc_datasubcl.html) section from the OPL User's manual.
 This sample shows how to read and write tuplesets to/from a database with Java. It also enables you to read a database and generate .dat files to be used in the IDE to prototype your optimization model.
 
-While this sample uses MySQL as data storage, it can be easily adapted to
-any database that has JDBC drivers.
+One [variation](examples/ilo_opl_call_java) of this sample shows how to read and write tuplesets to/from a database involving only some scripting in your .dat
+
+This sample comes with example connection configurations to DB2, MySQL and MS SQL Server. It can
+be easily adapted to any database that has JDBC drivers.
 This example will work with any 12.x OPL version, even if it is configured to run with 12.8.0 version.
 
 
 ## Table of Contents
    - [Prerequisites](#prerequisites)
-   - [Build and run the sample](#build-and-run-the-sample)
+   - [Build and run the sample from java](#build-and-run-the-sample-from-java)
       - [Build the sample](#build-the-sample)
       - [Run sample with DB2](#run-sample-with-db2)
       - [Run sample with MySQL](#run-sample-with-mysql)
-       - [Run sample with MS SQL Server](#run-sample-with-ms-sql-server)
+      - [Run sample with MS SQL Server](#run-sample-with-ms-sql-server)
+   - [Run the sample from OPL](#run-the-sample-from-opl)
    - [Export plain dat files](#export-plain-dat-files)
    - [Run with a previous OPL version](#run-with-a-previous-opl-version)
    - [License](#license)   
@@ -41,7 +44,10 @@ This example will work with any 12.x OPL version, even if it is configured to ru
    MySQL Comunity Server, but is compatible with minimal changes with other JDBC
    compatible databases.
 
-## Build and run the sample
+## Build and run the sample from java
+
+The default sample uses model and data from [examples/oil](examples/oil)
+
 ### Build the sample
 
 Before you build the sample, you must edit `build.properties` for the appropriate path locations:
@@ -203,6 +209,14 @@ $ ant run_mssql
 
 
 
+### Run the sample from OPL
+
+Sample in [examples/ilo_opl_call_java](examples/ilo_opl_call_java) shows how to
+use the jdbc custom data source as a library, without having the need to
+invoke OPL runtime from java. You can use this method to access database
+using a jdbc-custom-data-source from `oplrun` or OPL Studio.
+
+
 ### Reusing the sample with other databases
 As the sample is build on JDBC, it's possible to reuse <code>JdbcCustomDataSource</code> with minimal changes:
 

build.properties

@@ -3,7 +3,7 @@
 # Example for MySQL:
 mysql.jdbc.connector.path=external_libs/mysql-connector-java-5.1.40-bin.jar
 # Example for DB2:
-db2.jdbc.connector.path=C:/Program Files/IBM/SQLLIB/java/db2jcc4.jar
+db2.jdbc.connector.path=external_libs/db2jcc4.jar
 # MS SQL server
 sqlserver.jdbc.connector.path=external_libs/mssql-jdbc-7.2.2.jre8.jar
 

build.xml

@@ -72,19 +72,19 @@
 
     <target name="run_db2" depends="compile">
 		<antcall target="run">
-            <param name="cmd" value="-properties data/db_db2.xml data/oil.mod data/oil.dat"/>
+            <param name="cmd" value="-properties data/db_db2.xml examples/oil/oil.mod examples/oil/oil.dat"/>
 		</antcall>
     </target>
 
     <target name="run_mysql" depends="compile">
 		<antcall target="run">
-            <param name="cmd" value="-properties data/db_mysql.xml data/oil.mod data/oil.dat"/>
+            <param name="cmd" value="-properties data/db_mysql.xml examples/oil/oil.mod examples/oil/oil.dat"/>
 		</antcall>
     </target>
 
 	<target name="run_mssql" depends="compile">
 		<antcall target="run">
-            <param name="cmd" value="-properties data/db_mssql.xml data/oil.mod data/oil.dat"/>
+            <param name="cmd" value="-properties data/db_mssql.xml examples/oil/oil.mod examples/oil/oil.dat"/>
 		</antcall>
     </target>
 

examples/ilo_opl_call_java/README.md

@@ -0,0 +1,86 @@
+# Example using IloOplCallJava
+
+This sample is basically the same as [oil](../oil).
+
+The difference is that it does not involve writing code in Java, and can be used
+in a .dat/.mod from OPL Studio.
+
+# Setup
+
+Before you run the sample, you will need to edit [oil.dat](oil.dat), and configure
+paths. In particular, you want to add the JDBC connector jar, for instance:
+
+```
+  // Update this to point to your jdbc driver.
+  // For instance mssql-jdbc-7.2.2.jre8.jar for mssql
+  IloOplImportJava("../../external_libs/mssql-jdbc-7.2.2.jre8.jar")
+```
+
+And you want to specify the configuration file for your database connection:
+
+```
+  // This is the configuration file for accessing your database.
+  var jdbcConfigXml = "../../data/db_mssql.xml";
+```
+
+Lastly, you want to point to the jdbc custom data source jar.
+It is distributed as binaries in the [lib](../../lib) directory:
+
+```
+  // The jar containing the jdbc custom data source
+  IloOplImportJava("../../lib/jdbc-custom-data-source.jar");
+```
+# Running the sample
+
+To run the sample, invoke the `run.bat` script:
+
+
+```
+C:\> run
+Buildfile: C:\opl\OPL-jdbc-custom-data-source\examples\ilo_opl_call_java\build.xml
+
+platform:
+
+run:
+     [exec]
+     [exec] <<< setup
+     [exec]
+     [exec] Reading elements from database
+     [exec] Reading Gasolines using "SELECT NAME FROM GASDATA"
+     [exec] Reading OilData using "SELECT * FROM OILDATA"
+     [exec] Reading Oils using "SELECT NAME FROM OILDATA"
+     [exec] Reading GasData using "SELECT * FROM GASDATA"
+     [exec] Done
+     [exec]
+     [exec] <<< generate
+     [exec]
+     [exec] Tried aggregator 1 time.
+     [exec] LP Presolve eliminated 1 rows and 0 columns.
+     [exec] Reduced LP has 12 rows, 12 columns, and 43 nonzeros.
+     [exec] Presolve time = 0.00 sec. (0.01 ticks)
+     [exec]
+     [exec] Iteration log . . .
+     [exec] Iteration:     1   Scaled dual infeas =             0.000000
+     [exec] Iteration:     2   Dual objective     =        434000.000000
+     [exec]
+     [exec] <<< solve
+     [exec]
+     [exec]
+     [exec] OBJECTIVE: 287750
+     [exec] Result =  {<"Crude1" "Diesel" 800 0> <"Crude1" "Regular" 2111.1 750>
+
+     [exec]      <"Crude1" "Super" 2088.9 0> <"Crude2" "Diesel" 0 0>
+     [exec]      <"Crude2" "Regular" 4222.2 750> <"Crude2" "Super" 777.78 0>
+     [exec]      <"Crude3" "Diesel" 200 0> <"Crude3" "Regular" 3166.7 750>
+     [exec]      <"Crude3" "Super" 133.33 0>}
+     [exec]
+     [exec] <<< post process
+     [exec]
+     [exec]
+     [exec] <<< done
+     [exec]
+
+BUILD SUCCESSFUL
+Total time: 1 second
+Press any key to continue . . .
+```

examples/ilo_opl_call_java/build.xml

@@ -0,0 +1,31 @@
+<project name="externaldataread" default="run">
+	<property environment="env"/>
+	
+	<condition property="example.home" value="${env.CPLEX_STUDIO_DIR128}/opl">
+	<isset property="env.CPLEX_STUDIO_DIR128"/>
+	</condition>
+	<property name="example.home" value="${opl.home}">
+	</property>
+	
+	
+	<import file="${example.home}/examples/opl_interfaces/java/build_common.xml"/>
+	<condition property="oplrun.binary" value="oplrunjava">
+		<os family="unix"/>
+	</condition>
+	<property name="oplrun.binary" value="oplrun"/>
+
+	<target name="run" depends="platform">
+		<exec executable="${example.home}/bin/${example.platform}/${oplrun.binary}">
+			<arg value="oil.mod"/>
+			<arg value="oil.dat"/>
+			<env key="ODMS_JAVA_ARGS" value='-classpath "${example.home}/lib/oplall.jar"' />
+			<env key="PATH" path="${example.home}/bin/${example.platform}${platform.separator}${env.PATH}"/>
+			<env key="Path" path="${example.home}/bin/${example.platform}${platform.separator}${env.Path}"/>
+			<env key="LD_LIBRARY_PATH" path="${example.home}/bin/${example.platform}${platform.separator}${env.JAVA_HOME}/jre/bin${platform.separator}${env.JAVA_HOME}/jre/bin/j9vm${platform.separator}${env.JAVA_HOME}/jre/bin/classic"/>
+			<env key="LIBPATH" path="${example.home}/bin/${example.platform}${platform.separator}${env.JAVA_HOME}/jre/bin${platform.separator}${env.JAVA_HOME}/jre/bin/j9vm${platform.separator}${env.JAVA_HOME}/jre/bin/classic"/>
+			<env key="DYLD_LIBRARY_PATH" path="${example.home}/bin/${example.platform}${platform.separator}${env.DYLD_LIBRARY_PATH}"/>
+			<env key="LD_PRELOAD_64" path="${preload_64}"/>
+		</exec>
+	</target>
+
+</project>

examples/ilo_opl_call_java/oil.dat

@@ -0,0 +1,17 @@
+prepare {
+  // Update this to point to your jdbc driver.
+  // For instance mssql-jdbc-7.2.2.jre8.jar for mssql
+  IloOplImportJava("../../external_libs/mssql-jdbc-7.2.2.jre8.jar")
+
+  // This is the configuration file for accessing your database.
+  var jdbcConfigXml = "../../data/db_mssql.xml";
+
+  // The jar containing the jdbc custom data source
+  IloOplImportJava("../../lib/jdbc-custom-data-source.jar");
+  
+  IloOplCallJava("com.ibm.opl.customdatasource.JdbcCustomDataSource",
+                 "addDataSource", "", jdbcConfigXml, thisOplModel);
+}
+
+MaxProduction = 14000;
+ProdCost = 4;

examples/ilo_opl_call_java/oil.mod

@@ -0,0 +1,80 @@
+// --------------------------------------------------------------------------
+// Licensed Materials - Property of IBM
+//
+// 5725-A06 5725-A29 5724-Y48 5724-Y49 5724-Y54 5724-Y55
+// Copyright IBM Corporation 1998, 2013. All Rights Reserved.
+//
+// Note to U.S. Government Users Restricted Rights:
+// Use, duplication or disclosure restricted by GSA ADP Schedule
+// Contract with IBM Corp.
+// --------------------------------------------------------------------------
+
+
+{string} Gasolines = ...;
+{string} Oils = ...;
+tuple gasType {
+   string name;
+   float demand;
+   float price;
+   float octane;
+   float lead;
+}
+
+tuple oilType {
+   string name;
+   float capacity;
+   float price;
+   float octane;
+   float lead;
+}
+{gasType} GasData = ...;
+{oilType} OilData = ...;
+gasType Gas[Gasolines] = [ g.name : g | g in GasData ];
+oilType Oil[Oils] = [ o.name : o | o in OilData ];
+
+float MaxProduction = ...;
+float ProdCost = ...;
+
+
+dvar float+ a[Gasolines];
+dvar float+ Blend[Oils][Gasolines];
+
+
+maximize
+  sum( g in Gasolines , o in Oils )
+        (Gas[g].price - Oil[o].price - ProdCost) * Blend[o][g]
+         - sum( g in Gasolines ) a[g];
+
+subject to {
+   
+  ctDemand:  forall( g in Gasolines )
+               sum( o in Oils ) 
+                 Blend[o][g] == Gas[g].demand + 10 * a[g];
+   
+  ctCapacity:  forall( o in Oils )   
+                 sum( g in Gasolines ) 
+                   Blend[o][g] <= Oil[o].capacity;
+
+  ctMaxProd:  sum( o in Oils , g in Gasolines ) 
+                Blend[o][g] <= MaxProduction;
+ 
+  ctOctane:  forall( g in Gasolines )
+               sum( o in Oils ) 
+                 (Oil[o].octane - Gas[g].octane) * Blend[o][g] >= 0;
+  ctLead:  forall( g in Gasolines )
+             sum( o in Oils ) 
+               (Oil[o].lead - Gas[g].lead) * Blend[o][g] <= 0;
+}
+tuple result {
+  string oil;
+  string gas;
+  float blend;
+  float a;
+}
+
+{result} Result = 
+  { <o,g,Blend[o][g],a[g]> | o in Oils, g in Gasolines };
+  
+execute DISPLAY_RESULT{
+  writeln("Result = ",Result)
+}

examples/ilo_opl_call_java/run.bat

@@ -0,0 +1,19 @@
+@echo off
+rem Run the example
+
+rem If CPLEX_STUDIO_DIR128 is not already defined, add the following line :  
+rem CPLEX_STUDIO_DIR128=%~dp0\..\..\..\..\..
+
+cd %~dp0
+
+set "arg="
+:Loop
+IF "%1"=="" GOTO Continue
+    set "arg=%arg% %1"
+SHIFT
+GOTO Loop
+:Continue
+
+call "%CPLEX_STUDIO_DIR128%\opl\ant\bin\ant" -Dexample.arg.line="%arg%" run
+
+pause

examples/oil/README.md

@@ -0,0 +1,20 @@
+# Maximizing the profit of an oil company
+
+## Describe the business problem
+
+* An oil company manufactures different types of gasoline and diesel. Each type of gasoline is produced by blending different types of crude oils that must be purchased. The company must decide how much crude oil to buy in order to maximize its profit while respecting processing capacities and quality levels as well as satisfying customer demand.
+* Blending problems are a typical industry application of Linear Programming (LP). LP represents real life problems mathematically using an objective function to represent the goal that is to be minimized or maximized, together with a set of linear constraints which define the conditions to be satisfied and the limitations of the real life problem. The function and constraints are expressed in terms of decision variables and the solution, obtained from optimization engines such as IBM® ILOG® CPLEX®, provides the best values for these variables so that the objective function is optimized.
+* The oil-blending problem consists of calculating different blends of gasoline according to specific quality criteria.
+* Three types of gasoline are manufactured: super, regular, and diesel.
+* Each type of gasoline is produced by blending three types of crude oil: crude1, crude2, and crude3.
+* The gasoline must satisfy some quality criteria with respect to their lead content and their octane ratings, thus constraining the possible blendings.
+* The company must also satisfy its customer demand, which is 3,000 barrels a day of super, 2,000 of regular, and 1,000 of diesel.
+* The company can purchase 5,000 barrels of each type of crude oil per day and can process at most 14,000 barrels a day.
+* In addition, the company has the option of advertising a gasoline, in which case the demand for this type of gasoline increases by ten barrels for every dollar spent.
+* Finally, it costs four dollars to transform a barrel of oil into a barrel of gasoline.
+
+## Files
+
+`oil.mod` contains the OPL Model.
+
+`oil.dat` contains part of the input data. Mostly parameters for the problem, like max production and production cost. The missing input data sets (OilData and GasData are read from the database at run time using the sql queries defined in the database connection xml configuration file)