モジュール java.base
パッケージ java.lang.ref

クラスReference<T>

java.lang.Object
java.lang.ref.Reference<T>
型パラメータ:
T - 紹介のタイプ
直系の既知のサブクラス:
PhantomReference, SoftReference, WeakReference
public abstract sealed class Reference<T> extends Object permits PhantomReference<T>, SoftReference<T>, WeakReference<T> (not exhaustive)
参照オブジェクトための抽象基底クラスです。 このクラスは、すべての参照オブジェクトに対して共通のオペレーションを定義します。 参照オブジェクトはガベージ・コレクタと密接に連携して実装されるので、このクラスを直接サブクラス化することはできません。
シール済クラス階層グラフ:
参照の密封クラス階層グラフ参照の密封クラス階層グラフ
導入されたバージョン:
1.2

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    void
    clear()
    この参照オブジェクトをクリアします。
    protected Object
    clone()
    CloneNotSupportedExceptionをスローします。
    boolean
    enqueue()
    この参照オブジェクトをクリアし、それが登録されているキューに登録オブジェクトを追加します。
    T
    get()
    参照オブジェクトのリファレントを返します。
    boolean
    isEnqueued()
    非推奨。
    このメソッドは当初、参照オブジェクトがクリアされてエンキューされたかどうかをテストするために指定されていましたが、このテストを行うために実装されたことはありません。
    static void
    reachabilityFence(Object ref)
    指定された参照によって参照されるオブジェクトが、オブジェクトが到達不能になる可能性のあるプログラムの以前のアクションに関係なく、「強く到達可能な」のままであることを保証します。このため、参照されたオブジェクトは、少なくともこのメソッドが呼び出されるまでガベージ・コレクションによって再要求できません。
    final boolean
    refersTo(T obj)
    この参照オブジェクトの参照がobjかどうかをテストします。

    クラス java.lang.Objectで宣言されたメソッド

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

  • メソッドの詳細

    • get

      public T get()
      参照オブジェクトのリファレントを返します。 プログラムまたはガベージ・コレクタによって、この参照オブジェクトがすでにクリアされている場合、このメソッドはnullを返します。
      APIのノート:
      このメソッドは、参照への強い参照を戻します。 これにより、ガベージ・コレクタは後のコレクション・サイクルまで強く到達可能として処理する可能性があります。 refersToメソッドを使用すると、一部のオブジェクトが参照オブジェクトの参照であるかどうかをテストする際に、このような強化を回避できます。つまり、ref.get() == objではなくref.refersTo(obj)を使用します。
      戻り値:
      この参照が表すオブジェクト。この参照オブジェクトがクリアされている場合はnull
      関連項目:

    • refersTo

      public final boolean refersTo(T obj)
      この参照オブジェクトの参照がobjかどうかをテストします。 参照オブジェクトがクリアされている場合、null objを使用するとtrueが返されます。
      パラメータ:
      obj - この参照オブジェクト参照と比較するオブジェクト
      戻り値:
      objがこの参照オブジェクトの参照である場合はtrue
      導入されたバージョン:
      16

    • clear

      public void clear()
      この参照オブジェクトをクリアします。 このメソッドを呼び出しても、このオブジェクトはキューに入りません。

      このメソッドはJavaコードによってのみ呼び出されます。ガベージ・コレクタが参照をクリアするときは、このメソッドを呼び出さずに直接行います。

    • isEnqueued

      @Deprecated(since="16") public boolean isEnqueued()
      非推奨。
      このメソッドは当初、参照オブジェクトがクリアされてエンキューされたかどうかをテストするために指定されていましたが、このテストを行うために実装されたことはありません。 このメソッドは、固有の競合状態または関連するReferenceQueueがないことが原因で、誤用される可能性があります。 このメソッドを使用してクリティカル・リソースを解放するアプリケーションは、重大なパフォーマンスの問題を引き起こす可能性があります。 アプリケーションでは、エンキューされた参照オブジェクトを確実に判別するためにReferenceQueueを使用するか、この参照オブジェクトがクリアされたかどうかを判断するためにrefersTo(null)を使用する必要があります。
      この参照オブジェクトが関連付けられたキュー内にあるかどうかをテストします(ある場合)。 このメソッドは、次の条件がすべて満たされている場合にのみtrueを戻します:
      • この参照オブジェクトは、作成時にキューに登録されています
      • ガベージ・コレクタがこの参照オブジェクトをキューに追加したか、enqueue()が呼び出された場合
      • この参照オブジェクトはまだキューから削除されていません。
      それ以外の場合、このメソッドはfalseを返します。 この参照オブジェクトがクリアされているが、競合状態のためにエンキューされていない場合、このメソッドはfalseを返すことがあります。
      戻り値:
      この参照オブジェクトが関連付けられたキュー(もしあれば)内にある場合にのみtrue。

    • enqueue

      public boolean enqueue()
      この参照オブジェクトをクリアし、それが登録されているキューに登録オブジェクトを追加します。

      このメソッドはJavaコードによってのみ呼び出されます。ガベージ・コレクタが参照をキューに入れるときは、このメソッドを呼び出さずに直接行います。

      戻り値:
      この参照オブジェクトがキューに入れられた場合はtrue。すでにキューに入れられているか、作成時にキューに登録されなかった場合はfalse

    • clone

      protected Object clone() throws CloneNotSupportedException
      CloneNotSupportedExceptionをスローします。 Referenceは、効果的にクローニングできません。 かわりに新規のReferenceを構築します。
      オーバーライド:
      clone、クラスObject
      戻り値:
      通常の戻り値はありません
      例外:
      CloneNotSupportedException - 常時
      導入されたバージョン:
      11
      関連項目:

    • reachabilityFence

      public static void reachabilityFence(Object ref)
      指定された参照によって参照されるオブジェクトが、オブジェクトが到達不能になる可能性のあるプログラムの以前のアクションに関係なく、「強く到達可能な」のままであることを保証します。このため、参照されたオブジェクトは、少なくともこのメソッドが呼び出されるまでガベージ・コレクションによって再要求できません。 このメソッドを呼び出すだけで、ガベージ・コレクションやファイナライズが開始されることはありません。

      このメソッドは、ガベージ・コレクションに関して「強い到達性」の順序を設定します。 プログラム内に暗黙的にしか存在しないリレーションを制御 -- 到達可能性条件はガベージ・コレクションを引き起こす。 このメソッドは、synchronizedブロックまたはメソッドを使用する、または他の同期機能を使用することができない、または必要な制御を提供しない早すぎる終了の珍しい状況で使用するために設計されています。 このメソッドは、リクレイムが可視効果を持つ可能性がある場合にのみ適用されます。これは、正確性のための順序付け制御に依存する方法で実装されたファイナライザ(「Java言語仕様」の12.6の項を参照してください)を持つオブジェクトに対して可能です。

      APIのノート:
      仮想マシンが、オブジェクトへの参照がヒープに格納されることがないことを検出するたびに、ファイナライズが行われることがあります: ガベージ・コレクタは、たとえオブジェクトが到達不能になっている限り、そのオブジェクトのフィールドがまだ使用中であっても、オブジェクトを再要求することができます。 これは、クラスに関連付けられた簿記が配列インデックスによって管理される以下の例のような場合に、驚くほど望ましくない影響を及ぼすことがあります。 ここで、メソッドactionはreachabilityFenceを使用して、関連付けられたExternalResourceの簿記が実行される前にResourceオブジェクトが再利用されないようにします。特にここでは、ExternalResourceを保持する配列スロットがメソッドObject.finalize()でゼロにならないようにします。そうでなければ同時に実行することができます。 
       
 class Resource {
   private static ExternalResource[] externalResourceArray = ...

   int myIndex;
   Resource(...) {
     myIndex = ...
     externalResourceArray[myIndex] = ...;
     ...
   }
   protected void finalize() {
     externalResourceArray[myIndex] = null;
     ...
   }
   public void action() {
     try {
       // ...
       int i = myIndex;
       Resource.update(externalResourceArray[i]);
     } finally {
       Reference.reachabilityFence(this);
     }
   }
   private static void update(ExternalResource ext) {
     ext.status = ...;
   }
 }
      ここでは、の呼び出しは、actionの呼び出しがこのオブジェクトの最後の使用であったとしても、更新前にupdateの呼び出し後にreachabilityFenceを呼び出すと、配列スロットがObject.finalize()によってヌルされないことが保証されます。 これは、例えば、ユーザー・プログラムの使用が、このResourceへの他の参照を保持しない形式new Resource().action();を有する場合です。 finallyブロックにreachabilityFenceブロックが置かれ、メソッド内のすべてのパスで確実に呼び出されるようにします。 より複雑な制御パスを持つメソッドでは、reachabilityFenceがすべてのパスに沿って遭遇するように、さらに注意を払う必要があります。

      reachabilityFenceの使用をよりよくカプセル化することが時折可能です。 上の例を続けて、ファイナライザが既に(ヌル・アウト・スロット)を実行していても、メソッドupdateへの呼び出しが進行しても問題ない場合は、reachabilityFenceの使用をローカライズすることができます: 

       
 public void action2() {
   // ...
   Resource.update(getExternalResource());
 }
 private ExternalResource getExternalResource() {
   ExternalResource ext = externalResourceArray[myIndex];
   Reference.reachabilityFence(this);
   return ext;
 }

      メソッドreachabilityFenceは、それ自身が到達可能性を保証する構造では必要ありません。 たとえば、ロックされているオブジェクトは一般には再利用できないため、クラスResource (finalizeを含む)のすべてのメソッドでオブジェクトのすべてのアクセスがsynchronized (this)ブロックで囲まれていれば十分です。 (さらに、このようなブロックには、"一般に"免責条項の例外を除いて、無限ループまたはそれ自体が到達不能であってはなりません。) しかし、この手法が効率的、望ましい、または可能ではない場合、メソッドreachabilityFenceはより良い選択肢のままです。たとえば、デッドロックが発生するためです。

      パラメータ:
      ref - 参照。 nullの場合、このメソッドは効果がありません。
      導入されたバージョン:
      9