////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at
  http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////
:documentationPath: /pipeline/transforms/
:language: en_US
:description: This transform allows you to enter Java expressions that are used to calculate new values or replace values in fields.

= image:transforms/icons/janino.svg[User Defined Java Expression transform Icon, role="image-doc-icon"] User Defined Java Expression

[%noheader,cols="3a,1a", role="table-no-borders" ]
|===
|
== Description

This transform allows you to enter Java expressions that are used to calculate new values or replace values in fields. Any custom jar libraries that your expressions depend on need to be placed in the folder `plugins/transforms/janino/lib`

|
== Supported Engines
[%noheader,cols="2,1a",frame=none, role="table-supported-engines"]
!===
!Hop Engine! image:check_mark.svg[Supported, 24]
!Spark! image:question_mark.svg[Maybe Supported, 24]
!Flink! image:question_mark.svg[Maybe Supported, 24]
!Dataflow! image:question_mark.svg[Maybe Supported, 24]
!===
|===

== Usage

If you have a Java expression like :

[source,java]
----
C=A+B
----

Then you can simply enter the right side of the expression in the dialog:

[source,java]
----
A+B
----

The values are exposed to the expressions as the Java objects they are :

[options="header"]
|===
|Data type|Java Class
|BigNumber|BigDecimal
|Binary|byte[]
|Date|java.util.Date
|Integer|java.lang.Long
|Number|java.lang.Double
|String|java.lang.String
|===

== Options

[options="header"]
|===
|Option|Description
|Transform name|Specify a name for this transform. This must be unique wihin the pipeline.
|New field|The new field in the data stream that contains the result of the expression.
If you want to overwrite an existing field, you need to define the same field here and in the "Replace value" option.
|Java expression|The Java expression to evaluate. See examples below.
|Value type|The field's data type.
|Length|The maximum length of a string in the new field.
|Precision|The number of decimal places used to express numbers.
|Replace value|Set this to be identical to the "New field" name when you want to replace the value in an existing field.
|===

== Examples

**Add 2 integers, A and B**

[source,java]
----
A+B
----

**Concatenate 2 Strings : firstname and name and put a space in between**

[source,java]
----
firstname+" "+name
----

or if you really care about performance, this might be faster:

[source,java]
----
new StringBuffer(firstname).append(" ").append(name).toString()
----

**Use native Java and API functions**

[source,java]
----
System.getProperty("os.name")
----

**Business rules (If / Then / Else)**

[source,java]
----
a<c?true:false
----

This can be more complicated

[source,java]
----
a<c?(a==1?1:2):3
----

even with OR and AND and other operators and functions

**Using Constants**

If you use a constant, you may need to define the right type in some expressions otherwise it could throw an error. 
Eg if you use "0" that is "int" but Apache Hop "Integer" is "java.lang.Long", so you'll get an exception:

Incompatible expression types "int" and "java.lang.Long"

To solve this, use:

[source,java]
----
test == null ? new Long(0) : test
----

The above expression checks if "test" is null and replaces it with a zero Long.
Otherwise, it return "test" unchanged.

**Cut a string from end and test for null and minimal length**

Imagine you have input strings "location" like

    Orlando FL
    New York NY

and you want to separate the state and city. You could use the following expressions:

For state (get the last 2 characters):

[source,java]
----
location != null && location.length()>2 ? location.substring(location.length()-2, location.length()) : null
----

For city (get the beginning without the last 2 characters and trim):

[source,java]
----
location != null && location.length()>2 ? location.substring(0, location.length()-2).trim() : location
----

**Functionality of a LIKE operator (contains string)**

The following example returns 1 when abc is within the source string, otherwise 2. It returns also 2 when the source string is null.
If you prefer the return values to be of value type Integer, use "new Long(1)" and "new Long(2)".

[source,java]
----
samplestr != null && samplestr.indexOf("abc")>-1 ? 1 : 2
----

== Blocking specific code

As a simple security measure you can block the execution of code containing specific strings.
This can be done by adding exclusions to the `codeExclusions.xml` file located at <Hop Installation>/plugins/transforms/janino

Example:
[source,xml]
----
    <exclusions>
        <exclusion>System.</exclusion>
        <exclusion>HopVfs.</exclusion>
    </exclusions>
----
