Integrate Java API in a Java project

In this section, you will learn how to integrate the Java API generated by AlchemyJ in a Java project.

Initializing AlchemyJ Context

1. Import the generated package into your project.

2. Copy the libraries from AlchemyJ_Maven_Repository in the installation package to the local maven repository path.

   The above screen is Eclipse Preference window.

3. The package needs to be initialized before using it. Below is an example of how to initialize an AlchemyJ Java Package.

 public void initialize() {
    AlchemyjApiConfigurer apiConfigurer = AlchemyjApplication.getInstance().getApiConfigurer();
    // (Mandatory)
    // 1. Setup property holder.
    setupPropertyHolder(apiConfigurer.getInitProperties());

    // (Mandatory)
    // 2. Setup object mapper
    setupObjectMapper(apiConfigurer);

    // (Optional)
    // 3. Register external resources if necessary.
    registerExternalResource(apiConfigurer.getExternalResourceRegister());

    // (Mandatory)
    // 4. Execute initialize method
    // Note: This method can only be executed once!
    AlchemyjApplication.getInstance().init();
  }

Setup Property Holder

private void setupPropertyHolder(AlchemyjApiInitProperties apiInitProperties) {
    apiInitProperties.setStopOnFormulaError(true);
    apiInitProperties.setStopOnUserRaiseError(true);
    apiInitProperties.setThrowOnFormulaError(true);
    apiInitProperties.setThrowOnUserRaiseError(true);
    apiInitProperties.setThrowOnInputValueOutOfScope(true);

    // Setup property map, these two properties below are mandatory.
    // You can add your own property, which will be used in workbook, into this map.
    Map<String, String> propMap = createPropertyMap();
    apiInitProperties.setApplicationPropertiesMap(propMap);

    // You should setup either of items below, is anyone of them is correct,
    // license file location specification is done.
    apiInitProperties.setLicenseEvnVariableName("");
    apiInitProperties.setLicenseFileLocation(
        "C:\\AlchemyJ\\License\\AlchemyJ.lic");
  }

Setup Object Mapper

  private void setupObjectMapper(AlchemyjApiConfigurer apiConfigurer) {
    ObjectMapper objectMapper = new ObjectMapper();
    // You can set your own time-zone here, this may affect Date field serialization/deserialization
    objectMapper.setTimeZone(TimeZone.getDefault());
    apiConfigurer.setConfiguredJacksonObjectMapper(objectMapper);
  }

Register External Resource

private void registerExternalResource(
      AlchemyjExternalResourceRegister alchemyjExternalResourceRegister) {
    // 3.1 Register SMTP
    registerSmtpResource(alchemyjExternalResourceRegister);
    // 3.2 Register LDAP
    registerLdapResource(alchemyjExternalResourceRegister);
    // 3.3 Register Datasource
    registerDatasource(alchemyjExternalResourceRegister);
  }

Register Data Source

  private void registerDatasource(
      AlchemyjExternalResourceRegister alchemyjExternalResourceRegister) {
    String id = "myDataSourceId";
    AlchemyjDatabaseType type = AlchemyjDatabaseType.ORACLE;
    ComboPooledDataSource datasource = new ComboPooledDataSource();
    datasource.setJdbcUrl("jdbc:oracle:thin:@127.0.0.1:1521:orcl");
    datasource.setUser("user");
    datasource.setPassword("123456");
    AlchemyjDataSourceDescriptor dataSourceDescriptor1 =
        new AlchemyjDataSourceDescriptor(id, type, datasource);
    alchemyjExternalResourceRegister.registerDataSource(dataSourceDescriptor1);
    // alchemyjExternalResourceRegister.registerDataSource(dataSourceDescriptor1,dataSourceDescriptor2);
    // alchemyjExternalResourceRegister.registerDataSource(dataSourceDescriptor1,dataSourceDescriptor2, ...);
  }
}

Register SMTP Resource

private void registerSmtpResource(
      AlchemyjExternalResourceRegister alchemyjExternalResourceRegister) {
    AlchemyjSmtpConnDescriptor smtpConnDescriptor1 = new AlchemyjSmtpConnDescriptor();
    smtpConnDescriptor1.setIdentifierId("myIdentifierId");
    smtpConnDescriptor1.setSenderAddress("AxisoftDev@axisoft.com");
    smtpConnDescriptor1.setUsername("user");
    smtpConnDescriptor1.setPassword("123456");
    smtpConnDescriptor1.setHost("127.0.0.1");
    smtpConnDescriptor1.setPort("3322");
    alchemyjExternalResourceRegister.registerSmtpConnectionDefinition(smtpConnDescriptor1);
    // alchemyjExternalResourceRegister.registerSmtpConnectionDefinition(smtpConnDescriptor1,
    // smtpConnDescriptor2);
    // alchemyjExternalResourceRegister.registerSmtpConnectionDefinition(smtpConnDescriptor1,
    // smtpConnDescriptor2, ...);
  }

Register LDAP Resource

 private void registerLdapResource(
      AlchemyjExternalResourceRegister alchemyjExternalResourceRegister) {
    AlchemyjLdapDescriptor ldapDescriptor1 = new AlchemyjLdapDescriptor();
    ldapDescriptor1.setIdentifier("myLdapIdentifierId");
    ldapDescriptor1.setLdapUrl("ldap://127.0.0.1:3389/");
    ldapDescriptor1.setBase("ou=sample,dc=axisoft,dc=com");
    ldapDescriptor1.setUserName("user");
    ldapDescriptor1.setPassword("123456");
    alchemyjExternalResourceRegister.registerLdap(ldapDescriptor1);
    // alchemyjExternalResourceRegister.registerLdap(ldapDescriptor1,ldapDescriptor2);
    // alchemyjExternalResourceRegister.registerLdap(ldapDescriptor1,ldapDescriptor2, ...);
  }

Getting an object instance

Below is an example of how to get and close an object instance.

Create an object instance just like creating a normal java object from a java class:

CustomerObject customer = new CustomerObject();

After using the object, it should be closed.

CustomerObject customer = new CustomerObject();
....(Your logic code)
customer.close(); //to release the resources

Methods of AlchemyjApiInitProperties

• public void setStopOnFormulaError(boolean stopOnFormulaError)
  1. true: If there is native formula calculation error, stop and do not calculate other cells. The calculation order is dynamic.
  2. false: Ignore all formula calculation error, set error code back to the cell if error and continue to calculate all other cells.
  3. default: false
• public void setStopOnUserRaiseError(boolean stopOnUserRaiseError)
  1. true: If there is error raised by the formula ajRaiseError(), stop and do not calculate other cells. The calculation order is dynamic.
  2. false: Ignore all errors from ajRaiseError(), set error code back to the cell, and continue to calculate all other cells.
  3. default: true
• public void setThrowOnFormulaError(boolean throwOnFormulaError)
  1. true: If there is native formula calculation error, throw a Java Exception in generated Java code.
  2. false: If there is native formula calculation error, DO NOT throw a Java Exception in generated Java code.
  3. default: true
• public void setThrowOnUserRaiseError(boolean throwOnUserRaiseError)
  1. true: If there is error raised by formula: ajRaiseError(), throw a Java Exception in generated Java code.
  2. false: Ignore all errors from ajRaiseError(), DO NOT throw a Java Exception in generated Java code.
  3. default: true
• public void setThrowOnInputValueOutOfScope(boolean throwOnInputValueOutOfScope)
  1. true: If the input data out of defined data range, throw a Java Exception in generated Java code.
  2. false: Ignore errors when input data out of defined data range, DO NOT throw a Java Exception in generated Java code.
  3. default: false
• public void setApplicationPropertiesMap(Map<String,String> propertyMap)
  1. key: Should be the same as the value in column 'Name' in sheet '%%AppConfig'
  2. value: Property value, when a workbook is initialized, the value will be applied into cells corresponding to the 'key' cell, it may affect your formula result if the formula contains the cell which current value locates.
• public void setLicenseFileLocation(String path) The absolute path of your license file.
• public void setLicenseEvnVariableName(String name) The Environment Variable Name for your license file.
• public void setisGenerateExcelDumpFileOnDebugMode(boolean isGenerateExcelDumpFileOnDebugMode)
  1. true: Generate Excel dump file when running the unit test in debug mode.
  2. false: Do not generate Excel dump file when running the unit test in debug mode.
  3. default: false
• public void setExcelDumpFileLocation(String path) The file path of Excel dump file.