java

How does the SharedSecrets mechanism work?

jdk.internal.misc.SharedSecrets describes itself as:

A repository of "shared secrets", which are a mechanism for calling implementation-private methods in another package without using reflection. A package-private class implements a public interface and provides the ability to call package-private methods within that package; the object implementing that interface is provided through a third package to which access is restricted. This framework avoids the primary disadvantage of using reflection for this purpose, namely the loss of compile-time checking.

Can someone please provide an example that demonstrates how this mechanism enables classes in one package to access package-private methods in a different package?

Solution

  • Quoting Andrew John Hughes:

    When looking through OpenJDK for the VM project, I noticed that they have a rather interesting solution to this. This is encapsulated in sun.misc.SharedSecrets. This class provides access to instances of a number of public interfaces, such as sun.misc.JavaLangAccess. The actual implementations are provided as inner classes in the appropriate package e.g. java.lang, where it has access to the private and package-private variables and methods within.

    Say that you have API classes scattered across multiple packages. You want them to be able to access each other's internals, without exposing them to end-users. What do you do?

    Option 1: Without Java Modules

    1. Create an "internal" package that will be omitted from the public Javadoc (e.g. com.example.internal)
    2. Declare one or more interfaces in the internal package, referencing the private functionality you are trying to access.
    3. Declare a public class (e.g. SharedSecrets) in the internal package to hold implementations of these interfaces.
    4. Use static initializers in your API classes to get/set implementations of these interfaces from/to SharedSecrets.
    5. Now, API classes can access each other's internals by piggybacking through a trusted intermediary (SharedSecrets).

    Option 2: With Java Modules

    1. Say you have two modules: main and test, and you want test to access private or package-private methods and fields inside main.
    2. Declare a public class SharedSecrets inside the main module, in a non-exported package. For example: main.internal.SharedSecrets.
    3. In main's module-info.java, add exports main.internal to test.
    4. Meaning, the package main.internal will only be accessible to module test.
    5. Because SharedSecrets is public, anyone in main (even from different packages) can push bridge functions or fields into it. It actually works the other way as well (test can push bridge functions into main) but I've never needed to do this to date.
    6. Now, anytime test wishes to access the internals of main, it simply piggybacks its calls through SharedSecrets.

    This solution is especially nice because the resulting Javadoc and IDE auto-complete will look a lot cleaner.

    Concrete Example

    External Users
+-- external
¦   +-- EndUser.java
+-- module-info.java

Library
+-- library
¦   +-- character
¦   ¦   +-- Character.java
¦   +-- story
¦   ¦   +-- Story.java
¦   +-- internal
¦       +-- SharedSecrets.java
¦       +-- CharacterAccess.java
+-- module-info.java

    End-user code

    external/EndUser.java:

    package external;

import library.character.Character;
import library.story.Story;

public class EndUser
{
    public static void main(String[] args)
    {
        Story story = new Story();
        story.introduce(Character.HARRY_POTTER);
        story.introduce(Character.RON_WEASLEY);
        story.introduce(Character.HERMIONE_GRANGER);
    }
}

    module-info.java:

    module external
{
    requires library;
}

    Library code

    library/story/Story.java

    package library.story;

import library.character.Character;
import library.internal.CharacterAccess;
import library.internal.SharedSecrets;

public final class Story
{
    public void introduce(Character character)
    {
        System.out.println(character.name() + " enters the room and says: " + 
          SharedSecrets.getPhrase(character));
    }
}

    library/character/Character.java:

    package library.character;

import library.internal.CharacterAccess;
import library.internal.SharedSecrets;

public enum Character
{
    HARRY_POTTER
    {
        @Override
        String getPhrase()
        {
            return "Your bird, there was nothing I could do. He just caught fire.";
        }
    },
    RON_WEASLEY
    {
        @Override
        String getPhrase()
        {
            return "Who are you and what have you done with Hermione Granger?";
        }
    },
    HERMIONE_GRANGER
    {
        @Override
        String getPhrase()
        {
            return "I'm not an owl!";
        }
    };

    static
    {
        SharedSecrets.setCharacterAccess(new CharacterAccess()
        {
            @Override
            public String getPhrase(Character character)
            {
                return character.getPhrase();
            }
        });
    }

    abstract String getPhrase();
}

    library/internal/SharedSecrets.java:

    package library.internal;

public final class SharedSecrets
{
    private static final Lookup lookup = MethodHandles.lookup();
    private static CharacterAccess characterAccess;

    public static void setCharacterAccess(CharacterAccess characterAccess)
    {
        SharedSecrets.characterAccess = characterAccess;
    }

    public static String getPhrase(Character character)
    {
        CharacterAccess access = characterAccess;
        if (access == null)
        {
            initialize(Character.class);
            access = characterAccess;
            assert access != null;
        }
        return access.getPhrase(character);
    }

    /**
     * Initializes a class. If the class is already initialized, this method has no effect.
     *
     * @param c the class
     */
    private static void initialize(Class<?> c)
    {
        try
        {
            lookup.ensureInitialized(c);
        }
        catch (IllegalAccessException e)
        {
            throw new AssertionError(e);
        }
    }
}

    library/internal/CharacterAccess.java:

    package library.internal;

import library.character.Character;

public interface CharacterAccess
{
    String getPhrase(Character character);
}

    module-info.java:

    module library
{
    exports library.character;
    exports library.story;
}

    Output

    HARRY_POTTER enters the room and says: Your bird, there was nothing I could do. He just caught fire.

    RON_WEASLEY enters the room and says: Who are you and what have you done with Hermione Granger?

    HERMIONE_GRANGER enters the room and says: I'm not an owl!

    Notice