Using Payload

Utilising Payload is very simple.

1. Download the payload jar or distribution.
2. Run: java -jar payload-0.5.jar [new-jar.jar] {files...}
3. Take the jar to the desired unpacking location.
4. Run: java -jar [new-jar.jar]

Extraction-time search and replace

The chief reason for Payload is to create environment dependent install files. When deployed to a machine, a .properties file on the machine is used to configure the install file for that machine. This is how that may be done.

• Create a payload.properties file and make it the first file listed on step 2 above. It should contain something like the following:

       org.osjava.payload=true
       org.osjava.payload.interpolate.endsWith=txt
       org.osjava.payload.interpolate.endsWith=xml
       org.osjava.payload.interpolate.matches=regexp
       org.osjava.payload.interpolate.archive.endsWith=war
       org.osjava.payload.interpolate.archive.matches=regexp
       

  This specifies which files are interpolated. It also specifies that any .war files should have their constituent files interpolated too.
• Provide a .properties file on the target machine as a 2nd argument when unpacking. It should contain something like the following:

        VARIABLE=A value for the variable
        PORT=8080
        IP=127.0.0.1
       

  and the jar'd files should contain ${VARIABLE}, ${PORT} and ${IP}.
• This means you end up with two lines that look like:
  1. Run: java -jar payload-0.5.jar [new-jar.jar] [payload.properties] {files...}
  2. Run: java -jar [new-jar.jar] {some.properties}

Paylets - custom extraction behaviour

Sometimes a payload extraction with search and replace is not enough to create the right system. Paylets are a way to send Java code along with the self-extracting jar to provide custom functionality. They are executed after the extraction has occured, and have access to all available parameters.

Including a paylet is quite basic:

1. Code a Paylet against the org.osjava.payload.Paylet interface.
2. Store your paylet(s) and the classes they require in a jar file.
3. Create a payload.properties file. It should contain something like the following:

        org.osjava.payload=true
        org.osjava.payload.paylet=com.example.ExamplePaylet
        

   This hooks in one example paylet. Many paylets may be hooked in, for example:

        org.osjava.payload=true
        org.osjava.payload.paylet=com.example.ExamplePaylet
        org.osjava.payload.paylet=com.example.TestPaylet
        org.osjava.payload.paylet=com.example.ObfuscatePaylet
        

4. Run: java -jar payload-0.5.jar [new-jar.jar] [payload.properties] {-x example-paylet.jar} {files...}
5. Take the jar to the desired unpacking location.
6. Run: java -jar [new-jar.jar]