Skip to content

Utilities in SØAD

SØAD Framework provides several utility functions that help streamline common tasks like sending emails, generating PDFs, and others.

1. Email

SØAD includes a simple API to send emails using the mailer class.

Function Signature

send(sender_email, receiver_email, subject, content, cc=[], bcc=[], html=False, attachment=[], reply_to=None)

Parameters:

  • sender_email: The sender's email address.
  • receiver_email: The recipient's email address.
  • subject: Email subject line.
  • content: The body of the email (text or HTML).
  • html: Optional flag (True or False). If True, the content will be treated as HTML.
  • cc: Optional list of CC email addresses.
  • bcc: Optional list of BCC email addresses.
  • attachment: Optional list of file paths to attach to the email.
  • reply_to: Optional email address for reply-to header.

Example:

from utils import mailer

email_content = """
<h1>Welcome</h1>
<p>Your account has been created.</p>
"""

mailer.send("[email protected]", "[email protected]", "Welcome to SØAD", email_content, html=True)

You can also use render.as_view(...)() to generate email content from a view template.

2. PDF Generator

You can generate a PDF file from any XHTML-compatible HTML string using the pdf utility.

Function Signature

generate(content, pdf_file=None, outstream=None)

Parameters:

  • content: XHTML content as a string (typically generated using render.as_view(...)())
  • pdf_file: Optional File (java.io.File object) where the PDF will be saved.
  • outstream: Optional output stream to write the PDF content to. If not provided, it defaults to writing to pdf_file.

Example:

from utils import pdf, render

html = render.as_view(ctx, "invoice")()
pdf.generate(html, "/tmp/invoice.pdf")

This generates a PDF file containing the rendered invoice.

3. Google Guava Library

SØAD bundles Google Guava, a powerful set of Java core libraries that offer advanced capabilities for working with collections, IO, caching, and more.

Common Use Cases:

a. Reading and Writing Files

from com.google.common.io import Files
from java.io import File

file = File("/tmp/example.txt")
content = Files.toString(file, "UTF-8")
print(content)

Files.write("Hello World".getBytes(), file)

b. Base64 Encoding and Decoding

from com.google.common.io import BaseEncoding

encoded = BaseEncoding.base64().encode("hello world".getBytes())
print(encoded)  # aGVsbG8gd29ybGQ=

decoded = BaseEncoding.base64().decode(encoded)
print(String(decoded))

c. IO Streams

from com.google.common.io import ByteStreams
from java.io import FileInputStream, FileOutputStream

in_stream = FileInputStream("input.txt")
out_stream = FileOutputStream("output.txt")

ByteStreams.copy(in_stream, out_stream)

in_stream.close()
out_stream.close()

These utilities make working with lower-level Java APIs much easier and more expressive, and they integrate smoothly into your SØAD transactions and utilities.

4. Apache Commons & Apache POI Support

SØAD also bundles other powerful libraries to enhance backend functionality:

a. Apache Commons

SØAD includes several Apache Commons libraries such as:

  • commons-lang3 – string manipulation, object utilities, etc.
  • commons-io – input/output stream helpers

These can be imported and used directly in your transaction or utility classes to simplify everyday Java operations.

b. Apache POI (Excel Manipulation)

Apache POI enables you to read from and write to Microsoft Excel files (both .xls and .xlsx). It is useful for generating reports or importing/exporting spreadsheet data.

Please refer to Cookbook for examples on how to use Apache POI with SØAD.

If you need additional functionality beyond what’s provided out-of-the-box, you can upload custom .jar libraries into the /webapp/WEB-INF/lib/ folder. These JAR files will be loaded into the classpath at runtime, allowing you to use external Java libraries in your SØAD transactions.