IJavaPeerable.xml

<Type Name="IJavaPeerable" FullName="Java.Interop.IJavaPeerable">
  <TypeSignature Language="C#" Value="public interface IJavaPeerable : IDisposable" />
  <TypeSignature Language="ILAsm" Value=".class public interface auto ansi abstract beforefieldinit IJavaPeerable implements class System.IDisposable" />
  <TypeSignature Language="DocId" Value="T:Java.Interop.IJavaPeerable" />
  <TypeSignature Language="F#" Value="type IJavaPeerable = interface&#xA;    interface IDisposable" />
  <AssemblyInfo>
    <AssemblyName>Java.Interop</AssemblyName>
    <AssemblyVersion>0.1.0.0</AssemblyVersion>
    <AssemblyVersion>7.0.0.0</AssemblyVersion>
  </AssemblyInfo>
  <Interfaces>
    <Interface>
      <InterfaceName>System.IDisposable</InterfaceName>
    </Interface>
  </Interfaces>
  <Docs>
    <summary>
      Support for using Java object instances.
    </summary>
    <remarks>
      <para>
        The <c>IJavaPeerable</c> interface provides access to a Java object
        instance, invocation of members on that Java instance, control over
        the lifetime of that object instance, and callbacks for when the
        wrapper is being disposed or finalized.
        The following operations are permitted:
      </para>
      <list type="bullet">
        <item>
          <term>
            Object instance access is available through the
            <see cref="P:Java.Interop.IJavaPeerable.PeerReference" />
            property.
        </term>
        </item>
        <item>
          <term>
            Member access and invocation is available through the
            <see cref="P:Java.Interop.IJavaPeerable.JniPeerMembers" />
            property.
        </term>
        </item>
        <item>
          <term>
            Object lifetime control through
            <see cref="M:Java.Interop.IJavaPeerable.Dispose" /> and
            <see cref="M:Java.Interop.IJavaPeerable.DisposeUnlessReferenced" />
            methods.
        </term>
        </item>
        <item>
          <term>
            Value visibilty is controlled through
            <see cref="M:Java.Interop.IJavaPeerable.DisposeUnlessRegistered" />.
        </term>
        </item>
        <item>
          <term>
            Disposal and finalization callbacks through the
            <see cref="M:Java.Interop.IJavaPeerable.Disposed" /> and
            <see cref="M:Java.Interop.IJavaPeerable.Finalized" /> methods.
        </term>
        </item>
      </list>
      <block subset="none" type="note">
        <para>DO NOT IMPLEMENT THIS INTERFACE.</para>
        <para>
          Implementations of this interface are useless without a
          <see cref="P:Java.Interop.IJavaPeerable.PeerReference" />
          implementation which returns
          a non-<c>default(JniObjectReference)</c> value, which
          corresponds to <see langword="null" /> in the Java VM.
          While this can be done, it frequently isn't, resulting in
          "unexpected" <c>NullPointerException</c> errors from Java.
          Additionally, even though you can implement <c>PeerReference</c>,
          any implementation won't fit in with a garbage collector, resulting
          in either memory leaks or additional work to clean values up.
        </para>
      </block>
    </remarks>
  </Docs>
  <Members>
    <Member MemberName="Disposed">
      <MemberSignature Language="C#" Value="public void Disposed ();" />
      <MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void Disposed() cil managed" />
      <MemberSignature Language="DocId" Value="M:Java.Interop.IJavaPeerable.Disposed" />
      <MemberSignature Language="F#" Value="abstract member Disposed : unit -&gt; unit" Usage="iJavaPeerable.Disposed " />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyName>Java.Interop</AssemblyName>
        <AssemblyVersion>7.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Called when the instance has been disposed.</summary>
        <remarks>
          <para>
        The <c>Disposed</c> method is invoked after the
        <see cref="M:System.IDisposable.Dispose" /> method has
        been invoked on the instance.
        The <see cref="P:Java.Interop.IJavaPeerable.PeerReference" />
        property is still valid when <c>Disposed</c> is invoked.
      </para>
          <block subset="none" type="usage">
        This method should only be invoked by the
        <see cref="T:Java.Interop.JniRuntime" /> instance which will
        be managing the <c>IJavaPeerable</c> value.
      </block>
          <block subset="none" type="overrides">
            <para>
          If the type is following the typical <c>IDisposable</c>
          pattern, then the <c>Disposed</c> method should delegate to
          the <c>Dispose(bool)</c> method.
          The proscribed implementation template is:
        </para>
            <code lang="C#">
[JniTypeSignature ("my/Example")]
partial class ExampleBinding : IJavaPeerable {

	public void Dispose ()
	{
        JniEnvironment.Runtime.ValueManager.Dispose (this);
	}

	protected virtual void Dispose (bool disposing)
	{
	}

	void IJavaPeerable.Disposed ()
	{
	    Dispose (disposing: true);
	}
}
        </code>
          </block>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="DisposeUnlessReferenced">
      <MemberSignature Language="C#" Value="public void DisposeUnlessReferenced ();" />
      <MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void DisposeUnlessReferenced() cil managed" />
      <MemberSignature Language="DocId" Value="M:Java.Interop.IJavaPeerable.DisposeUnlessReferenced" />
      <MemberSignature Language="F#" Value="abstract member DisposeUnlessReferenced : unit -&gt; unit" Usage="iJavaPeerable.DisposeUnlessReferenced " />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyName>Java.Interop</AssemblyName>
        <AssemblyVersion>7.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>
      If there are no outstanding references to this instance, then
      calls <c>Dispose()</c>; otherwise, does nothing.
    </summary>
        <remarks>
          <para>
        Call this method when you would like to allow instances to be
        collectable as soon as possible, but not if the current instance
        is referenced anywhere else.
      </para>
          <block subset="none" type="note">
        "not referenced anywhere else" may mean "is not registered".
      </block>
          <block subset="none" type="overrides">
            <para>
          The proscribed implementation template is:
        </para>
            <code lang="C#">
[JniTypeSignature ("my/Example")]
partial class ExampleBinding : IJavaPeerable {

	public void DisposeUnlessReferenced ()
	{
        JniEnvironment.Runtime.ValueManager.DisposeUnlessReferenced (this);
	}
}
        </code>
          </block>
        </remarks>
        <altmember cref="M:Java.Interop.IJavaPeerable.UnregisterFromRuntime" />
      </Docs>
    </Member>
    <Member MemberName="Finalized">
      <MemberSignature Language="C#" Value="public void Finalized ();" />
      <MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void Finalized() cil managed" />
      <MemberSignature Language="DocId" Value="M:Java.Interop.IJavaPeerable.Finalized" />
      <MemberSignature Language="F#" Value="abstract member Finalized : unit -&gt; unit" Usage="iJavaPeerable.Finalized " />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyName>Java.Interop</AssemblyName>
        <AssemblyVersion>7.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Called when the instance has been finalized.</summary>
        <remarks>
          <para>
        The <c>Finalized</c> method is invoked after the finalizer
        has been invoked on the instance.
        The <see cref="P:Java.Interop.IJavaPeerable.PeerReference" />
        property is NOT valid when <c>Finalized</c> is invoked.
      </para>
          <block subset="none" type="usage">
        This method should only be invoked by the
        <see cref="T:Java.Interop.JniRuntime" /> instance which will
        be managing the <c>IJavaPeerable</c> value.
      </block>
          <block subset="none" type="overrides">
            <para>
          If the type is following the typical <c>IDisposable</c>
          pattern, then the <c>Finalized</c> method should delegate to
          the <c>Dispose(bool)</c> method.
          The proscribed implementation template is:
        </para>
            <code lang="C#">
[JniTypeSignature ("my/Example")]
partial class ExampleBinding : IJavaPeerable {

	~ExampleBinding ()
	{
        JniEnvironment.Runtime.ValueManager.TryCollectObject (this);
	}

	protected virtual void Dispose (bool disposing)
	{
	}

	void IJavaPeerable.Finalized ()
	{
	    Dispose (disposing: false);
	}
}
        </code>
          </block>
        </remarks>
        <altmember cref="P:Java.Interop.IJavaPeerable.PeerReference" />
      </Docs>
    </Member>
    <Member MemberName="JniIdentityHashCode">
      <MemberSignature Language="C#" Value="public int JniIdentityHashCode { get; }" />
      <MemberSignature Language="ILAsm" Value=".property instance int32 JniIdentityHashCode" />
      <MemberSignature Language="DocId" Value="P:Java.Interop.IJavaPeerable.JniIdentityHashCode" />
      <MemberSignature Language="F#" Value="member this.JniIdentityHashCode : int" Usage="Java.Interop.IJavaPeerable.JniIdentityHashCode" />
      <MemberType>Property</MemberType>
      <AssemblyInfo>
        <AssemblyName>Java.Interop</AssemblyName>
        <AssemblyVersion>7.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>System.Int32</ReturnType>
      </ReturnValue>
      <Docs>
        <summary>
      Returns the value of <c>java.lang.System.identityHashCode()</c>
      for the wrapped instance.
    </summary>
        <value>To be added.</value>
        <remarks>
          <block subset="none" type="usage">
        This property <i>will not</i> throw a
        <see cref="T:System.ObjectDisposedException" /> after the instance
        has been disposed.
      </block>
          <block subset="none" type="overrides">
        The <c>JniIdentityHashCode</c> property should return the value
        last passed to
        <see cref="M:Java.Interop.IJavaPeerable.SetJniIdentityHashCode" />.
      </block>
        </remarks>
        <altmember cref="M:Java.Interop.IJavaPeerable.SetJniIdentityHashCode" />
      </Docs>
    </Member>
    <Member MemberName="JniManagedPeerState">
      <MemberSignature Language="C#" Value="public Java.Interop.JniManagedPeerStates JniManagedPeerState { get; }" />
      <MemberSignature Language="ILAsm" Value=".property instance valuetype Java.Interop.JniManagedPeerStates JniManagedPeerState" />
      <MemberSignature Language="DocId" Value="P:Java.Interop.IJavaPeerable.JniManagedPeerState" />
      <MemberSignature Language="F#" Value="member this.JniManagedPeerState : Java.Interop.JniManagedPeerStates" Usage="Java.Interop.IJavaPeerable.JniManagedPeerState" />
      <MemberType>Property</MemberType>
      <AssemblyInfo>
        <AssemblyName>Java.Interop</AssemblyName>
        <AssemblyVersion>7.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>Java.Interop.JniManagedPeerStates</ReturnType>
      </ReturnValue>
      <Docs>
        <summary>State of the managed peer.</summary>
        <value>To be added.</value>
        <remarks>
          <para>
        A <see cref="T:Java.Interop.JniManagedPeerStates" /> value providing
        the state of the current Managed Peer instance.
        <format type="text/html">
          (<a href="https://developer.xamarin.com/guides/android/advanced_topics/garbage_collection/#Cross-VM_Object_Collections">Definitions</a>)
        </format></para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="JniPeerMembers">
      <MemberSignature Language="C#" Value="public Java.Interop.JniPeerMembers JniPeerMembers { get; }" />
      <MemberSignature Language="ILAsm" Value=".property instance class Java.Interop.JniPeerMembers JniPeerMembers" />
      <MemberSignature Language="DocId" Value="P:Java.Interop.IJavaPeerable.JniPeerMembers" />
      <MemberSignature Language="F#" Value="member this.JniPeerMembers : Java.Interop.JniPeerMembers" Usage="Java.Interop.IJavaPeerable.JniPeerMembers" />
      <MemberType>Property</MemberType>
      <AssemblyInfo>
        <AssemblyName>Java.Interop</AssemblyName>
        <AssemblyVersion>7.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>Java.Interop.JniPeerMembers</ReturnType>
      </ReturnValue>
      <Docs>
        <summary>
      Member access and invocation support.
    </summary>
        <value>To be added.</value>
        <remarks>
          <block subset="none" type="usage">
        This property <i>will not</i> throw a
        <see cref="T:System.ObjectDisposedException" /> after the instance
        has been disposed.
      </block>
          <block subset="none" type="overrides">
            <para>
          The <c>JniPeerMembers</c> property may be accessed before the
          constructor has executed, as common behavior is for the
          <c>JniPeerMembers</c> to be access virtually to permit caching
          of constructor <c>jmethodID</c>s.
        </para>
            <para>
          The proscribed implementation template is:
        </para>
            <code lang="C#">
[JniTypeSignature ("my/Example")]
partial class ExampleBinding {
    static readonly JniPeerMembers _members = new JniPeerMembers ("my/Example", typeof (ExampleBinding));
    public override JniPeerMembers JniPeerMembers {
        get {return _members;}
    }
}
        </code>
          </block>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="PeerReference">
      <MemberSignature Language="C#" Value="public Java.Interop.JniObjectReference PeerReference { get; }" />
      <MemberSignature Language="ILAsm" Value=".property instance valuetype Java.Interop.JniObjectReference PeerReference" />
      <MemberSignature Language="DocId" Value="P:Java.Interop.IJavaPeerable.PeerReference" />
      <MemberSignature Language="F#" Value="member this.PeerReference : Java.Interop.JniObjectReference" Usage="Java.Interop.IJavaPeerable.PeerReference" />
      <MemberType>Property</MemberType>
      <AssemblyInfo>
        <AssemblyName>Java.Interop</AssemblyName>
        <AssemblyVersion>7.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>Java.Interop.JniObjectReference</ReturnType>
      </ReturnValue>
      <Docs>
        <summary>
      Returns a
      <see cref="T:Java.Interop.JniObjectReference" /> of the wrapped
      Java object instance.
    </summary>
        <value>To be added.</value>
        <remarks>
          <block subset="none" type="usage">
        This property <i>will not</i> throw a
        <see cref="T:System.ObjectDisposedException" /> after the instance
        has been disposed.
      </block>
          <block subset="none" type="note">
            <para>
          THIS VALUE WILL CHANGE OVER TIME. It is NOT stable.
          It may potentially change during any future GC.
          DO NOT use this value as a key in a dictionary.
          The <see cref="P:Java.Interop.IJavaPeerable.JniIdentityHashCode" />
          property may be used for that purpose.
        </para>
            <para>
          While the value can change, the <c>PeerReference</c> property
          should always refer to the same Java instance.
          (Multiple different JNI handle values may refer to the same
          Java instance.)
        </para>
          </block>
          <block subset="none" type="overrides">
        The <c>JniIdentityHashCode</c> property should return the value
        last passed to
        <see cref="M:Java.Interop.IJavaPeerable.SetJniIdentityHashCode" />.
      </block>
        </remarks>
        <altmember cref="M:Java.Interop.IJavaPeerable.SetPeerReference" />
      </Docs>
    </Member>
    <Member MemberName="SetJniIdentityHashCode">
      <MemberSignature Language="C#" Value="public void SetJniIdentityHashCode (int value);" />
      <MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void SetJniIdentityHashCode(int32 value) cil managed" />
      <MemberSignature Language="DocId" Value="M:Java.Interop.IJavaPeerable.SetJniIdentityHashCode(System.Int32)" />
      <MemberSignature Language="F#" Value="abstract member SetJniIdentityHashCode : int -&gt; unit" Usage="iJavaPeerable.SetJniIdentityHashCode value" />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyName>Java.Interop</AssemblyName>
        <AssemblyVersion>7.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="value" Type="System.Int32" />
      </Parameters>
      <Docs>
        <param name="value">
      A <see cref="T:System.Int32" /> which contains the value that future
      invocations of the
      <see cref="P:Java.Interop.IJavaPeerable.JniIdentityHashCode" />
      property should return.
    </param>
        <summary>Set the value returned by <c>JniIdentityHashCode</c>.</summary>
        <remarks>
          <para>
        The <c>SetJniIdentityHashCode</c> method is invoked to alter
        the value returned by future access to the
        <seealso cref="P:Java.Interop.IJavaPeerable.JniIdentityHashCode" />
        property.
      </para>
          <block subset="none" type="usage">
        This method should only be invoked by the
        <see cref="T:Java.Interop.JniRuntime" /> instance which will
        be managing the <c>IJavaPeerable</c> value.
      </block>
        </remarks>
        <altmember cref="P:Java.Interop.IJavaPeerable.JniIdentityHashCode" />
      </Docs>
    </Member>
    <Member MemberName="SetJniManagedPeerState">
      <MemberSignature Language="C#" Value="public void SetJniManagedPeerState (Java.Interop.JniManagedPeerStates value);" />
      <MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void SetJniManagedPeerState(valuetype Java.Interop.JniManagedPeerStates value) cil managed" />
      <MemberSignature Language="DocId" Value="M:Java.Interop.IJavaPeerable.SetJniManagedPeerState(Java.Interop.JniManagedPeerStates)" />
      <MemberSignature Language="F#" Value="abstract member SetJniManagedPeerState : Java.Interop.JniManagedPeerStates -&gt; unit" Usage="iJavaPeerable.SetJniManagedPeerState value" />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyName>Java.Interop</AssemblyName>
        <AssemblyVersion>7.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="value" Type="Java.Interop.JniManagedPeerStates" />
      </Parameters>
      <Docs>
        <param name="value">To be added.</param>
        <summary>To be added.</summary>
        <remarks>
          <para>Portions of this page are modifications based on work created and shared by the <format type="text/html"><a href="https://developers.google.com/terms/site-policies" title="Android Open Source Project">Android Open Source Project</a></format> and used according to terms described in the <format type="text/html"><a href="https://creativecommons.org/licenses/by/2.5/" title="Creative Commons 2.5 Attribution License">Creative Commons 2.5 Attribution License.</a></format></para>
        </remarks>
        <!-- No matching elements were found for the following include tag -->
        <include file="../Documentation/Java.Interop/IJavaPeerable.xml" path="/docs/member[@name='M:SetJniManagedPeerState']/*" />
      </Docs>
    </Member>
    <Member MemberName="SetPeerReference">
      <MemberSignature Language="C#" Value="public void SetPeerReference (Java.Interop.JniObjectReference reference);" />
      <MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void SetPeerReference(valuetype Java.Interop.JniObjectReference reference) cil managed" />
      <MemberSignature Language="DocId" Value="M:Java.Interop.IJavaPeerable.SetPeerReference(Java.Interop.JniObjectReference)" />
      <MemberSignature Language="F#" Value="abstract member SetPeerReference : Java.Interop.JniObjectReference -&gt; unit" Usage="iJavaPeerable.SetPeerReference reference" />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyName>Java.Interop</AssemblyName>
        <AssemblyVersion>7.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="reference" Type="Java.Interop.JniObjectReference" />
      </Parameters>
      <Docs>
        <param name="reference">
      A <see cref="T:Java.Interop.JniObjectReference" /> which contains the
      value that future invocations of the
      <see cref="P:Java.Interop.IJavaPeerable.PeerReference" />
      property should return.
    </param>
        <summary>Set the value returned by <c>PeerReference</c>.</summary>
        <remarks>
          <para>
        The <c>SetPeerReference</c> method is invoked to alter
        the value returned by future access to the
        <seealso cref="P:Java.Interop.IJavaPeerable.PeerReference" />
        property.
      </para>
          <block subset="none" type="usage">
        This method should only be invoked by the
        <see cref="T:Java.Interop.JniRuntime" /> instance which will
        be managing the <c>IJavaPeerable</c> value.
      </block>
        </remarks>
        <altmember cref="P:Java.Interop.IJavaPeerable.PeerReference" />
      </Docs>
    </Member>
    <Member MemberName="UnregisterFromRuntime">
      <MemberSignature Language="C#" Value="public void UnregisterFromRuntime ();" />
      <MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void UnregisterFromRuntime() cil managed" />
      <MemberSignature Language="DocId" Value="M:Java.Interop.IJavaPeerable.UnregisterFromRuntime" />
      <MemberSignature Language="F#" Value="abstract member UnregisterFromRuntime : unit -&gt; unit" Usage="iJavaPeerable.UnregisterFromRuntime " />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyName>Java.Interop</AssemblyName>
        <AssemblyVersion>7.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>
      Unregister this instance so that the runtime will not return
      it from future
      <see cref="M:Java.Interop.JniRuntime+JniValueManager.PeekValue" />
      invocations.
    </summary>
        <remarks>
          <para>
        Call this method when you would like to prevent this instance
        from being returned by future
        <see cref="M:Java.Interop.JniRuntime+JniValueManager.PeekValue" />
        invocations.
      </para>
          <block subset="none" type="overrides">
            <para>
          The proscribed implementation template is:
        </para>
            <code lang="C#">
[JniTypeSignature ("my/Example")]
partial class ExampleBinding : IJavaPeerable {

	public void UnregisterFromRuntime ()
	{
        JniEnvironment.Runtime.ValueManager.UnRegisterObject (this);
	}
}
        </code>
          </block>
        </remarks>
      </Docs>
    </Member>
  </Members>
</Type>