cz.gyarab.util.collection

Class AutoCloseables<T extends java.lang.AutoCloseable>

java.lang.Object

cz.gyarab.util.collection.AutoCloseables<T>

Type Parameters:

T - typ elementu kolekce

All Implemented Interfaces:

java.lang.AutoCloseable

public final class AutoCloseables<T extends java.lang.AutoCloseable>
extends java.lang.Object
implements java.lang.AutoCloseable

Kolekce objektů, které implementují AutoCloseable. Kolekce samotná implementuje toto rozhraní také. Při zavírání kolekce se rozvněž zavřou všechny elementy. Elementem může být i kolekce, takže lze snadno vytvořit hierarchickou strukturu.

Primárním účelem této kolekce je zajištění uzavření objektů, které zapomněl provést programátor-uživatel těchto objektů. V normální situaci programátor postupuje tak, že nebezpečný kód uzavře do try-catch-finally nebo try-with-resources bloku:

 // try-catch-finally
 AutoCloseable tcf = new ...;
 try {
   ...
 } finally {
   tcf.close();
 }
 // try-with-resources
 try (AutoCloseable twr = new ...) {
   ...
 }
 

V takovém případě je vše v pořádku. Ale programátor je tvor zapomnětlivý, při nezavření může objekt blokovat nějaký prostředek, v klient-serverové aplikaci dokonce i po svém ukončení. Programátor-tvůrce objektu tak má nelehký úkol uvolnit prostředky, jakmile nejsou potřeba. A ty nejsou určitě ve chvíli, kdy zmizí poslední reference na objekt a carbage collector se rozhodne objekt zfinalizovat. Tak nezbývá, než zavření svěřit metodě Object.finalize(). Jenže ani to není stoprocentní, při ukončení aplikace se objekty nefinalizují.

A tak nastává čas pro AutoCloseables. Následuje vzorové použití:

 public class SafeObject implements AutoCloseable {
   private static final AutoCloseables<SafeObject> CLOSE = AutoCloseables.create();
   public SafeObject() {
     ...
     CLOSE.register(this);
   }
   @Override
   protected void finalize() {
     close();
     super.finalize();
   }
   @Override
   public void close() {
     CLOSE.unregister(this);
     ...
   }
 }
 

Při dodržení tohoto návrhové vzoru je vysoce provaděpodobné, že objekt, jehož včasné a řádné zavření nám leží na srdci, se hned po svém vytvoření zařadí do registru (pozor na přetížené konstruktory, musí se registrovat v každém a měl by jen jednou), pak žije a dělá něco užitečného, pokud je programátor-uživatel spolehlivý, hned po použití je objekt uzavřen, tedy vyřazen z registru, pak se zruší jeho reference, dojde k finalizaci a druhému uzavření (což by měl finalizátor zvládnout, i kdyby byla vyvolána výjimka) a druhému vyřazení z registru (což registr zvládne).

Při opomenutí uzavření buď GC rozhodne o vyřazení objektu a zavolá finalizaci, které následně zavolá první zavření a první vyřazení, nebo aplikace skončí bez finalizace, tak nastupuje naše kolekce, která si ukončení aplikace hlídá, pokud tou dobou jsou v kolekci zbylé (nezavřené a nevyřazené) objekty, zavře a vyřadí je sama, teprve až nebude mít žádnou referenci otevřenou, dovolí aplikaci její ukončení.

Since:

1.4

Method Summary

Modifier and Type	Method and Description
void	close() Zavře sebe a všechny držené elementy.
static <T extends java.lang.AutoCloseable> AutoCloseables<T>	create() Vytvoří samozavírací kolekci bez rodiče, tedy na nejvyšší úrovni.
static <T extends java.lang.AutoCloseable> AutoCloseables<T>	create(AutoCloseables<AutoCloseables> parent) Vytvoří samozavírací kolekci s rodičem.
T	register(T obj) Registruje objekt do kolekce.
boolean	unregister(T obj) Odregistruje objekt z kolekce.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static <T extends java.lang.AutoCloseable> AutoCloseables<T> create()

Vytvoří samozavírací kolekci bez rodiče, tedy na nejvyšší úrovni. Většina implementací využije tuto formu.

Type Parameters:

T - typ elementu, který bude kolekce držet, typicky třída, ve které se ochrana před zapomenutým zavřením tvoří

Returns:

nově vytvořenou kolekci schopnou se nejpozději před ukončením aplikace sebe a všechny své elementy zavřít

create

public static <T extends java.lang.AutoCloseable> AutoCloseables<T> create(AutoCloseables<AutoCloseables> parent)

Vytvoří samozavírací kolekci s rodičem. Většina implementací spíše využije formu bez rodiče.

Type Parameters:

T - typ elementu, který bude kolekce držet, typicky třída, ve které se ochrana před zapomenutým zavřením tvoří

Parameters:

parent - rodičovská kolekce pro hierarchické uspořádání (uzavřením rodiče se také zavřou všechny sesterské objekty)

Returns:

nově vytvořenou kolekci schopnou se nejpozději před ukončením aplikace sebe a všechny své elementy zavřít

register

public T register(T obj)
           throws java.lang.IllegalStateException

Registruje objekt do kolekce. Pokud se sám neodregistruje, při vlastním zavření, což je nejpozději těsně před ukončením aplikace, kolekce objekt zavře sama.

Parameters:

obj - registrovaný objekt

Returns:

referenci na registrovaný objekt (takže lze použít techniku zřetězení metod)

Throws:

java.lang.IllegalStateException - pokud registrace probíhá v okamžiku, kdy už je kolekce uzavřena

unregister

public boolean unregister(T obj)

Odregistruje objekt z kolekce. Pokud objekt v kolekci není (a třeba ani nikdy nebyl) nebo je kolekce již uzavřená (a z principu prázdná nebo vyoprazdňující se), metoda potichu tuto skutečnost ignoruje (nevyvolá výjimku).

Parameters:

obj - odregistrovávaný objekt

Returns:

true, pokud se podařilo objekt najít odstranit (ne zavřít)

close

public void close()

Zavře sebe a všechny držené elementy. Pokud těmito elementy jsou další kolekce, propaguje se zavření i na ně a jejich elementy. Elementy implementují stejné rozhraní a tedy i tuto metodu. Musejí být tolerantní k případnému vícenásobnému zavření.

Specified by:

close in interface java.lang.AutoCloseable