Interface Initable

All Superinterfaces:

Proxy

All Known Subinterfaces:

DebugController, MemoryMonitor, NetworkMonitor, PowerProfileMonitor

All Known Implementing Classes:

CharsetConverter, Collection, DBusConnection, DBusObjectManagerClient, DBusProxy, DBusServer, DebugController.DebugController$Impl, DebugControllerDBus, InetAddressMask, Initable.Initable$Impl, Item, MemoryMonitor.MemoryMonitor$Impl, NetworkMonitor.NetworkMonitor$Impl, PowerProfileMonitor.PowerProfileMonitor$Impl, Prompt, Service, Socket, Subprocess, WebExtension

@Generated("org.javagi.JavaGI")
public interface Initable
extends Proxy

GInitable is implemented by objects that can fail during initialization. If an object implements this interface then it must be initialized as the first thing after construction, either via init(Cancellable) or AsyncInitable.initAsync(int, Cancellable, AsyncReadyCallback) (the latter is only available if it also implements AsyncInitable).

If the object is not initialized, or initialization returns with an error, then all operations on the object except g_object_ref() and g_object_unref() are considered to be invalid, and have undefined behaviour. They will often fail with org.gnome.glib.GLib.critical or org.gnome.glib.GLib.warning, but this must not be relied on.

Users of objects implementing this are not intended to use the interface method directly, instead it will be used automatically in various ways. For C applications you generally just call new_(Type, Cancellable, GError[], String, Object...) directly, or indirectly via a foo_thing_new() wrapper. This will call init(Cancellable) under the cover, returning NULL and setting a GError on failure (at which point the instance is unreferenced).

For bindings in languages where the native constructor supports exceptions the binding could check for objects implementing GInitable during normal construction and automatically initialize them, throwing an exception on failure.

Since:

2.22

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	Initable.Initable$Impl	The Initable$Impl type represents a native instance of the Initable interface.
static class	Initable.InitableIface	Provides an interface for initializing object such that initialization may fail.

Method Summary

Modifier and Type	Method	Description
static @Nullable Type	getType()	Get the GType of the Initable class.
default boolean	init(@Nullable Cancellable cancellable)	Initializes the object implementing the interface.
static GObject	new_(Type objectType, @Nullable Cancellable cancellable, GError[] error, @Nullable String firstPropertyName, Object... varargs)	Helper function for constructing GInitable object.
static GObject	newv(Type objectType, @Nullable Parameter @Nullable [] parameters, @Nullable Cancellable cancellable)	Deprecated. Use g_object_new_with_properties() and g_initable_init() instead.

Methods inherited from interface Proxy

handle

Method Details

getType

static @Nullable Type getType()

Get the GType of the Initable class.

Returns:

the GType

new_

static GObject new_(Type objectType,
 @Nullable Cancellable cancellable,
 GError[] error,
 @Nullable String firstPropertyName,
 Object... varargs)

Helper function for constructing GInitable object. This is similar to g_object_new() but also initializes the object and returns null, setting an error on failure.

Parameters:

objectType - a GType supporting GInitable.

cancellable - optional GCancellable object, null to ignore.

error - a GError location to store the error occurring, or null to ignore.

firstPropertyName - the name of the first property, or null if no properties

varargs - the value if the first property, followed by and other property value pairs, and ended by null.

Returns:

a newly allocated GObject, or null on error

Since:

2.22

newv

@Deprecated
static GObject newv(Type objectType,
 @Nullable Parameter @Nullable [] parameters,
 @Nullable Cancellable cancellable)
             throws GErrorException

Deprecated.

Use g_object_new_with_properties() and g_initable_init() instead. See GParameter for more information.

Helper function for constructing GInitable object. This is similar to g_object_newv() but also initializes the object and returns null, setting an error on failure.

Parameters:

objectType - a GType supporting GInitable.

parameters - the parameters to use to construct the object

cancellable - optional GCancellable object, null to ignore.

Returns:

a newly allocated GObject, or null on error

Throws:

GErrorException - see GError

Since:

2.22

init

default boolean init(@Nullable Cancellable cancellable)
              throws GErrorException

Initializes the object implementing the interface.

This method is intended for language bindings. If writing in C, g_initable_new() should typically be used instead.

The object must be initialized before any real use after initial construction, either with this function or g_async_initable_init_async().

Implementations may also support cancellation. If cancellable is not null, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error IOErrorEnum.CANCELLED will be returned. If cancellable is not null and the object doesn't support cancellable initialization the error IOErrorEnum.NOT_SUPPORTED will be returned.

If the object is not initialized, or initialization returns with an error, then all operations on the object except g_object_ref() and g_object_unref() are considered to be invalid, and have undefined behaviour. See the Gio.Initable#description for more details.

Callers should not assume that a class which implements GInitable can be initialized multiple times, unless the class explicitly documents itself as supporting this. Generally, a class’ implementation of init() can assume (and assert) that it will only be called once. Previously, this documentation recommended all GInitable implementations should be idempotent; that recommendation was relaxed in GLib 2.54.

If a class explicitly supports being initialized multiple times, it is recommended that the method is idempotent: multiple calls with the same arguments should return the same results. Only the first call initializes the object; further calls return the result of the first call.

One reason why a class might need to support idempotent initialization is if it is designed to be used via the singleton pattern, with a GObjectClass.constructor that sometimes returns an existing instance. In this pattern, a caller would expect to be able to call g_initable_init() on the result of g_object_new(), regardless of whether it is in fact a new instance.

Parameters:

cancellable - optional GCancellable object, null to ignore.

Returns:

true if successful. If an error has occurred, this function will return false and set error appropriately if present.

Throws:

GErrorException - see GError

Since:

2.22