dunaj.host API
version 0.7.0
Host interoperability.
Arrays and batches have more functionalities defined in separate namespaces, dunaj.host.array and dunaj.host.batch.
Documentation needs more work. |
.
Available since version 1.0 (view source)
MACRO
(. & args)
The '.' macro is the basis for access to host. It can be considered a member-access operator, and/or read as 'in the scope of'.
If the first operand is a symbol that resolves to a class name,
the access is considered to be to a static member of the named
class. Note that nested classes are named
EnclosingClass$NestedClass
, if supported by host. Otherwise it
is presumed to be an instance member and the first argument is
evaluated to produce the target object.
If the second operand is a symbol and no args are supplied it is taken to be a field access - the name of the field is the name of the symbol, and the value of the expression is the value of the field, unless there is no argument public method of the same name, in which case it resolves to a call to the method.
If the second operand is a list, or args are supplied, it is taken to be a method call. The first item of the list must be a simple symbol, and the name of the method is the name of the symbol. The args, if any, are evaluated from left to right, and passed to the matching method, which is called, and its value returned. If the method has a void return type, the value of the expression will be nil. Note that placing the method name in a list with any args is optional in the canonic form, but can be useful to gather args in macros built upon the form.
See also: dunaj.host/..
..
Available since version 1.0 (alias of clojure.core/..)
MACRO
(.. x form)
(.. x form & more)
Expands into a member access (.)
of the first member on the
first argument, followed by the next member on the result, etc.
See also: dunaj.host/.
AnyArray
Available since version 1.0 (view source)
VAR
of type ArraySignature
A type signature for heterogeneous host arrays or host arrays with unspecified item type.
See also: Array
, ArrayManager
, dunaj.host.array/array-manager
AnyBatch
Available since version 1.0 (view source)
VAR
of type Signature
A type signature representing batch.
See also: Batch
, BatchManager
, dunaj.host.batch/batch-manager
Array
Available since version 1.0 (view source)
- Usage:
-
-
(Array sig)
-
- Type signature:
-
-
(Signature) → ArraySignature
-
Returns a type signature for a host array that has items
satisfying type signature sig
, or returns AnyArray.
Assumes that host supports arrays with unspecified type and that host arrays are hinted through non-primitive type hints.
See also: AnyArray
, ArrayManager
, dunaj.host.array/array-manager
ArrayManager
Available since version 1.0 (view source)
VAR
of type Signature
A type signature representing array manager.
Array manager provides following host methods:
-
(^java.lang.Class itemType [])
- returns item type -
(allocate [^int size])
- returns new array of given size -
(duplicate [arr])
- returns new array with content copied from arr -
(duplicate [arr ^int begin ^int end])
- returns new array with content copied from array section arr -
(^int count [arr])
- returns number of items in the array -
(get [arr ^int index])
- returns item at given position -
(set [arr ^int index val])
- sets item at given position -
(copyToBatch [arr ^java.nio.Buffer buf ^int offset ^int length])
- copies contents from arr into batch buf -
(sort [arr])
- sorts the array in place with natural ordering.
See also: Array
, AnyArray
, dunaj.host.array/array-manager
Batch
Available since version 1.0 (view source)
- Usage:
-
-
(Batch sig)
-
- Type signature:
-
-
(Signature) → Signature
-
Returns a type signature for a host batch that has items
satisfying type signature sig
, or returns AnyBatch
if
signature is not supported by host.
Assumes that host supports generic batches and that host batches are hinted through non-primitive type hints.
See also: AnyBatch
, BatchManager
, dunaj.host.batch/batch-manager
BatchManager
Available since version 1.0 (view source)
VAR
of type Signature
A type signature representing batch manager.
Batch manager provides following host methods:
-
(^java.lang.Class itemType [])
- returns item type -
(^java.nio.Buffer wrap [arr ^int offset ^int length])
- returns new batch which wraps given array section -
(^java.nio.Buffer allocate [^int size])
- returns new batch with given size -
(^java.nio.Buffer readOnly [^java.nio.Buffer buf])
- returns new batch which shares data but is read only -
(get [^java.nio.Buffer buf])
- returns item at current position and increases position -
(get [^java.nio.Buffer buf ^int index])
- returns item at given position -
(^java.nio.Buffer put [^java.nio.Buffer buf val])
- puts item and increases posision -
(^java.nio.Buffer put [^java.nio.Buffer buf ^int index val])
- puts item at given position -
(^java.nio.Buffer copy [^java.nio.Buffer src ^java.nio.Buffer dst])
- copy contents from src batch to dst batch -
(^java.nio.Buffer copy [^java.nio.Buffer src arr ^int offset ^int length])
- copy content from src batch to arr array.
See also: Batch
, AnyBatch
, dunaj.host.batch/batch-manager
Class
Available since version 1.0 (view source)
TYPE
A host class type.
This type is not available in Dunaj lite,
please use Class+ instead.
|
See also: class?
, class
, class-instance?
, Class+
Class+
Available since version 1.0 (view source)
TYPE
A host class type.
Identical to Class type, meant to be used in Dunaj lite.
|
See also: class
, class-instance?
, Class
bases
Available since version 1.0 (alias of clojure.core/bases)
not referred automatically
- Usage:
-
-
(bases c)
-
- Type signature:
-
-
(Class) → [Class]
-
Returns the immediate superclass and direct interfaces of
c
, if any.
See also: supers
, class-instance?
bean→map
Available since version 1.0 (alias of clojure.core/bean)
- Usage:
-
-
(bean->map x)
-
- Type signature:
-
-
(Any) → {clojure.lang.Keyword Any}
-
Takes a Java object and returns a read-only implementation of the map abstraction based upon its JavaBean properties.
class
Available since version 1.0 (alias of clojure.core/class)
- Usage:
-
-
(class x)
-
- Type signature:
-
-
(Any) → Class
-
Returns the Class of x
.
See also: Class
, class-instance?
, ensure-class-instance
class-instance?
Available since version 1.0 (alias of clojure.core/instance?)
- Usage:
-
-
(class-instance? c x)
-
- Type signature:
-
-
(Class ⨯ Any) → Boolean+
-
Returns true
is x
is an instance of the class c
,
otherwise returns true
.
See also: class
, ensure-class-instance?
, dunaj.poly/instance?
class?
Available since version 1.0 (view source)
not referred automatically
- Usage:
-
-
(class? x)
-
Type signature: Predicate
Returns true
if object x
is an instance of Class
type, false
otherwise.
See also: Class
, class
, class-instance?
, Class+
definterface
Available since version 1.0 (alias of clojure.core/definterface2)
MACRO
(definterface name & sigs)
Creates a new Java interface with the given name and method sigs. The method return types and parameter types may be specified with type hints, defaulting to Object if omitted.
(definterface MyInterface
(^int method1 [x])
(^Bar method2 [^Baz b ^Quux q]))
See also: dunaj.poly/defprotocol
, gen-class
, gen-interface
ensure-class-instance
Available since version 1.0 (alias of clojure.core/cast)
- Usage:
-
-
(ensure-class-instance c x)
-
- Type signature:
-
-
(Class ⨯ Any) → Any
-
Returns x
, throwing if x
cannot be cast to class c
.
See also: class
, class-instance?
gen-class
Available since version 1.0 (alias of clojure.core/gen-class)
not referred automatically
MACRO
(gen-class & options)
When compiling, generates compiled bytecode for a class with the
given package-qualified :name
(which, as all names in these
parameters, can be a string or symbol), and writes the .class
file to the ompile-path directory. When not compiling, does
nothing. The gen-class construct contains no implementation, as
the implementation will be dynamically sought by the generated
class in functions in an implementing Clojure namespace.
Given a generated class org.mydomain.MyClass
with a method
named mymethod, gen-class will generate an implementation that
looks for a function named by (str prefix mymethod)
(default prefix: '-') in a Clojure namespace specified by
:impl-ns
(defaults to the current namespace). All inherited
methods, generated methods, and init and main functions
(see :methods
, :init
, and :main
below) will be found
similarly prefixed. By default, the static initializer for the
generated class will attempt to load the Clojure support code for
the class as a resource from the classpath, e.g. in the example
case, org/mydomain/MyClass__init.class
.
This behavior can be controlled by :load-impl-ns
Note that methods with a maximum of 18 parameters are supported.
In all subsequent sections taking types, the primitive types can be referred to by their Java names (int, float etc), and classes in the java.lang package can be used without a package qualifier. All other classes must be fully qualified.
Options should be a set of key/value pairs, all except for
:name
are optional:
-
:name aname
- The package-qualified name of the class to be generated -
:extends aclass
- Specifies the superclass, the non-private methods of which will be overridden by the class. If not provided, defaults to Object. -
:implements [interface …]
- One or more interfaces, the methods of which will be implemented by the class. -
:init name
- If supplied, names a function that will be called with the arguments to the constructor. Must return[ [superclass-constructor-args] state]
If not supplied, the constructor args are passed directly to the superclass constructor and the state will benil
-
:constructors {[param-types] [super-param-types], …}
- By default, constructors are created for the generated class which match the signature(s) of the constructors for the superclass. This parameter may be used to explicitly specify constructors, each entry providing a mapping from a constructor signature to a superclass constructor signature. When you supply this, you must supply an :init specifier. -
:post-init name
- If supplied, names a function that will be called with the object as the first argument, followed by the arguments to the constructor. It will be called every time an object of this class is created, immediately after all the inherited constructors have completed. Its return value is ignored. -
:methods [ [name [param-types] return-type], …]
- The generated class automatically defines all of the non-private methods of its superclasses/interfaces. This parameter can be used to specify the signatures of additional methods of the generated class. Static methods can be specified with^{:static true}
in the signature’s metadata. Do not repeat superclass/interface signatures here. -
:main boolean
- If supplied and true, a static public main function will be generated. It will pass each string of theString[]
argument as a separate argument to a function called(str prefix main)
. -
:factory name
- If supplied, a (set of) public static factory function(s) will be created with the given name, and the same signature(s) as the constructor(s). -
:state name
- If supplied, a public final instance field with the given name will be created. You must supply an:init
function in order to provide a value for the state. Note that, though final, the state can be a ref or agent, supporting the creation of Java objects with transactional or asynchronous mutation semantics. -
:exposes {protected-field-name {:get name :set name}, …}
- Since the implementations of the methods of the generated class occur in Clojure functions, they have no access to the inherited protected fields of the superclass. This parameter can be used to generate public getter/setter methods exposing the protected field(s) for use in the implementation. -
:exposes-methods {super-method-name exposed-name, …}
- It is sometimes necessary to call the superclass' implementation of an overridden method. Those methods may be exposed and referred in the new method implementation by a local name. -
:prefix string
- Default: '-'. Methods called e.g. Foo will be looked up in vars called prefixFoo in the implementing ns. -
:impl-ns name
- Default: the name of the current ns. Implementations of methods will be looked up in this namespace. -
:load-impl-ns boolean
- Default:true
. Causes the static initializer for the generated class to reference the load code for the implementing namespace. Should betrue
when implementing-ns is the default,false
if you intend to load the code via some other method.
See also: gen-interface
, dunaj.lib/ns
gen-interface
Available since version 1.0 (alias of clojure.core/gen-interface)
not referred automatically
MACRO
(gen-interface & options)
When compiling, generates compiled bytecode for an interface with
the given package-qualified :name
(which, as all names in these
parameters, can be a string or symbol), and writes the .class
file to the compile-path directory. When not compiling, does
nothing.
In all subsequent sections taking types, the primitive types can be referred to by their Java names (int, float etc), and classes in the java.lang package can be used without a package qualifier. All other classes must be fully qualified.
Options should be a set of key/value pairs, all except for :name
are optional:
-
:name aname
- The package-qualified name of the class to be generated -
:extends [interface …]
- One or more interfaces, which will be extended by this interface. -
:methods [ [name [param-types] return-type], …]
- This parameter is used to specify the signatures of the methods of the generated interface. Do not repeat superinterface signatures here.
See also: gen-class
, dunaj.lib/ns
, definterface
keyword→class
Available since version 1.0 (view source)
MACRO
(keyword->class k)
Returns class from a given keyword k
or nil
if keyword is
not recognized.
See also: provide-class
new
Available since version 1.0 (view source)
not referred automatically
MACRO
(new classname & args)
Returns a new object constructed by calling constructor of the
class named by classname
, passing args
evaluated from
left to right into the constructor.
See also: class-instance?
, dunaj.host/.
, dunaj.host/..
provide-class
Available since version 1.0 (view source)
MACRO
(provide-class x)
Returns class from a given keyword, type or class, or returns nil
if x
is not recognized.
See also: keyword->class
proxy
Available since version 1.0 (alias of clojure.core/proxy)
MACRO
(proxy class-and-interfaces args & fs)
Where
-
class-and-interfaces
- a vector of class names -
args
- a (possibly empty) vector of arguments to the superclass constructor. -
f
-(name [params*] body)
or(name ([params*] body) ([params+] body) …)
Expands to code which creates a instance of a proxy class that implements the named class/interface(s) by calling the supplied fns. A single class, if provided, must be first. If not provided it defaults to Object.
The interfaces names must be valid interface types. If a method
fn is not provided for a class method, the superclass methd will
be called. If a method fn is not provided for an interface method,
an UnsupportedOperationException will be thrown should it be
called. Method fns are closures and can capture the environment
in which proxy is called. Each method fn takes an additional
implicit first arg, which is bound to this
. Note that while
method fns can be provided to override protected methods, they
have no other access to protected members, nor to super, as
these capabilities cannot be proxied.
See also: proxy-super
proxy-super
Available since version 1.0 (alias of clojure.core/proxy-super)
MACRO
(proxy-super meth & args)
Use to call a superclass method in the body of a proxy method.
Note that expansion captures this
.
See also: proxy
set!
Available since version 1.0 (view source)
MACRO
(set! field-access-form expr)
Assigns evaluated expr
to the field identified by
field-access-form
. Returns nil
.
Returning nil is a change from Clojure, as set! special
form autoboxes returned value and it is preferred for mutating fns
to return nil anyway.
|
supers
Available since version 1.0 (alias of clojure.core/supers)
not referred automatically
- Usage:
-
-
(supers c)
-
- Type signature:
-
-
(Class) → [Class]
-
Returns the immediate and indirect superclasses and interfaces
of c
, if any.
See also: bases
, class-instance?