Javadocs for Python users

This guide covers best practices for reading Javadocs as a Python user. Deephaven's query engine is written in Java, and Deephaven query strings can call Java, so knowing how to read Javadocs helps you find the Java methods you can call in your queries and get the most out of them.

What are Javadocs?

Javadoc generates API-level documentation called Javadocs from Java source code. Javadocs are the primary source of documentation for Java libraries. Deephaven's Javadocs document Deephaven's Java classes and methods. When you first land on Deephaven's Javadocs, you see this:

Deephaven Javadoc landing page with search bar and package list

The landing page contains a top menu bar, a search bar, and a list of packages. Most Python users only need the search bar. Calculate a median shows how to search for a method with it. The package list is useful for browsing, and Packages, interfaces, classes, and methods explains what it holds.

Why would a Python user need to use Javadocs?

You don't need the Javadocs for ordinary Python API calls such as update or agg_by. You need them when you write query strings: the engine compiles them to Java regardless of which API you use, so the functions built into them are Java methods.

Those built-in methods are also the fast choice. A query performs best when it keeps Java in Java and Python in Python, so prefer a built-in method over a Python function in a query string. That matters most on real-time and large tables, where a formula runs again for every row that's added or whose inputs change. For why, see The Python-Java boundary.

Deephaven's query library includes many built-in methods and fields that you can and should take full advantage of, and the Javadocs document all of them. A field is Java's term for a variable that belongs to a class or object, like a Python attribute.

Java concepts for Python users

Each of the following subsections explains a Java concept you meet when reading a Javadoc page. This is not a comprehensive list. The first subsection covers packages, interfaces, classes, and methods, which organize Javadoc pages much as modules and classes organize Python code. The other four concepts differ most from Python, and the following table summarizes them:

ConceptPythonJava
Naming conventionssnake_casecamelCase
Data typesDynamically typedStatically typed. Every variable and parameter has a declared type, fixed at compile time.
Method overloadingOptional arguments with default valuesMethod overloading
Varargs*argsVarargs (...)

Packages, interfaces, classes, and methods

The Javadoc landing page contains a list of Java packages. But what is a Java package? It's not much different from a Python package in that it contains Java code that's part of an API. Java uses packages to group similar classes and interfaces, much as a file system uses folders to group similar files.

For instance, the io.deephaven.api.agg package contains the classes and interfaces of Deephaven's Java API for aggregations. Deephaven's Python analogue, deephaven.agg, wraps that Java code, so it offers many of the same aggregations.

A Java package typically contains one or more interfaces and one or more classes. A Java class is similar to a Python class: a blueprint for building a certain type of object.

A Java interface mostly declares methods without implementing them. Classes that implement the interface supply the method bodies. Interfaces are a way to achieve abstraction, which hides implementation details from users.

Interfaces can also define static methods directly. A static method belongs to the class or interface itself rather than to an object, like a Python @staticmethod, so you call it without creating an object first. For instance, the Deephaven Java interface io.deephaven.api.agg.Aggregation defines a static factory method for every aggregation type Deephaven offers.

Java methods live within classes and interfaces. Continuing the Aggregation example, io.deephaven.api.agg.Aggregation.AggAbsSum is a static method that creates and returns an absolute sum aggregation. It's a member of an interface, which is a member of a package.

Javadocs follow the same hierarchy: each package page lists its interfaces and classes, and each interface or class page lists its fields, constructors, and methods.

Naming conventions

Deephaven's Python API follows standard Python conventions outlined in PEP 8. Deephaven's Java code, including Java code in query strings, follows standard Java naming conventions. The naming rules that matter most when reading Javadocs are:

  • In Python, functions and variables use snake_case. In Java, they use camelCase.
  • Java classes and interfaces use PascalCase, which capitalizes the first letter of every word (for example, Aggregation or Numeric). Python classes follow the same rule.
  • Some Deephaven factory methods break this convention. The static methods on Aggregation, such as AggPct and AggAbsSum, start with a capital letter.

Because of these exceptions, don't rely on case alone to tell a method from a class. Javadoc search lists methods under Members, and each class page lists its methods in a method summary.

Data types

Java is statically typed, whereas Python is dynamically typed. In Java, every variable and method parameter has a declared type that is fixed at compile time, which is why every parameter in a Javadoc method signature lists its type.

Java data types fall into two categories, primitives and objects. A type name in a Javadoc signature usually tells them apart by case:

  • Primitives are basic types with no fields or methods. Their names start with a lowercase letter, such as boolean, int, long, and double.
  • Objects, like Python objects, have fields and methods. Their class names start with an uppercase letter, such as Integer and Boolean.

Arrays are the exception: they are objects even when the element type is a primitive, as in double[] or the varargs double....

Each primitive has a matching wrapper class that holds the value as an object, such as Integer for int and Boolean for boolean. Javadoc pages often list a separate method for each. For example, Numeric has both median(double...), which takes double values, and median(Double[]), which takes an array of Double objects. The median example uses the first. Method overloading explains how Java tells them apart.

Python has only a few numeric types, such as int and float. Python's int has no fixed size, and its float is always 64 bits, like Java's double. NumPy adds more sized types, such as int32 and float32, that line up with the other Java primitives. For how Deephaven maps Java types to Python and NumPy types, see data types in Deephaven.

Method overloading

Java supports method overloading: two methods can share a name if they accept different parameters. Java has no optional arguments, so overloading fills the role that optional arguments with defaults play in Python.

Deephaven's Javadocs contain many overloaded methods. For instance, the Aggregation interface has four overloads of AggPct, which builds the same kind of percentile aggregation as Python's agg.pct. You don't call AggPct from Python, but its signatures show the patterns you see on any Javadoc page:

Each AggPct in the block above is a different method, despite having the same name. Java picks which method to call from the number and types of the arguments.

Varargs

Java calls a parameter that accepts a variable number of arguments of one type a varargs parameter, short for variable arguments. Its type ends in ..., as in the String... pairs parameter of the AggPct overloads shown in Method overloading. When reading a varargs signature, keep these rules in mind:

  • The ... means "zero or more".
  • A varargs parameter must be the method's last parameter.
  • Varargs correspond to Python's *args. Java has no equivalent of **kwargs.

For the overload AggPct(double percentile, String... pairs), each of the following Java calls is valid:

Java's varargs syntax allows a call with no values, but a method can still throw an error at runtime when it receives none. AggPct throws an IllegalArgumentException if you pass no column name pairs.

The signatures of methods you call in query strings read the same way. The median example calls the varargs overload median(double...).

Examples

Each example starts from a goal, reads the signatures of the Javadoc method that meets it, and calls that method in a query string. The first example shows how to find the method with the Javadoc search bar. The others start from a class that query strings import by default.

Calculate a median

Let's assume you have a table of OHLC data for a particular stock. Your column names are Open, High, Low, and Close, and they all contain double values. You want to calculate the median of the four values in each row. Start by searching for median in the search bar:

Javadoc search results after searching for 'median'

That's a lot of results. Classes and interfaces aren't what you want here. Methods, along with fields, appear under the Members heading in the search results. To narrow the search further, include the parameter type. The columns hold double values, so search for median(double:

Refined Javadoc search results for 'median(double'

The first result, median(double...) in the io.deephaven.function.Numeric class, is the one you want: it takes any number of double values. The Double[] and DoubleVector overloads further down each take a single array or vector, which isn't what this table holds.

Each Numeric row is followed by a matching io.deephaven.libs.GroovyStaticImports entry. That class is a generated wrapper that Groovy scripts use, and its entries only link back to Numeric, so open the Numeric entry to read the documentation.

Query strings import Numeric by default, so you can call its methods without an import statement.

When you pass column names to a method in a query string, the engine passes the values from each row and picks the overload that matches their types. With this knowledge in hand, computing the median of OHLC data is easy. The following example creates the data with new_table and adds a MedianOHLC column with update:

Generate pseudorandom numbers

Say you want to test your query against some random data. Deephaven's io.deephaven.function.Random class contains many pseudorandom number generators. Query strings import it by default, so you can call its methods without an import statement. The Javadocs list two overloads of randomDouble:

The first method generates a single random value that is at least min and less than max. The second generates an array of size random values in the same range. The following example calls both in an update on an empty_table:

Apply math functions to an integer column

Say you want the absolute value and sign of an int column, and the square root of its absolute value. io.deephaven.function.Numeric, the class from the median example, lists these and many more common math functions, all available in query strings. Most have a separate overload for each numeric input type. For example, sqrt(int) takes an int and returns a double, while abs(int) and signum(int) both return an int:

Key takeaways

Keep the following tips in mind when using Javadocs:

  • Be specific when using the search bar to limit the number of results you get.
    • If you're looking for a method, look under Members in results.
    • Use data types when searching for methods.
  • In a query string, you can pass a column name where a Java method expects a primitive such as double or int. The engine passes the column's value from each row and picks the overload that matches its type.
  • For how Java's naming, typing, overloading, and varargs differ from Python's, see the table in Java concepts for Python users.