Package ghidra.framework.protocol.ghidra

# Class GhidraURL

java.lang.Object
ghidra.framework.protocol.ghidra.GhidraURL

public class GhidraURL extends Object
Supported URL forms include:

- ghidra://<host>:<port>/<repository-name>[/<folder-path>]/[<folderItemName>[#ref]]
- ghidra:/[X:/]<project-path>/<project-name>[?[/<folder-path>]/[<folderItemName>[#ref]]]

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `MARKER_FILE_EXTENSION`
  `static final String`
  `PROJECT_DIRECTORY_EXTENSION`
  `static final String`
  `PROTOCOL`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String`
  `getDisplayString(URL url)`
  Generate preferred display string for Ghidra URLs.
  `static URL`
  `getFolderURL(URL ghidraUrl)`
  Force the specified URL to specify a folder.
  `static URL`
  `getNormalizedURL(URL url)`
  Get a normalized URL which eliminates use of host names and optional URL ref which may prevent direct comparison.
  `static String`
  `getProjectPathname(URL ghidraUrl)`
  Get the project pathname referenced by the specified Ghidra file/folder URL.
  `static ProjectLocator`
  `getProjectStorageLocator(URL localProjectURL)`
  Get the project locator which corresponds to the specified local project URL.
  `static URL`
  `getProjectURL(URL ghidraUrl)`
  Get Ghidra URL which corresponds to the local-project or repository with any file path or query details removed.
  `static String`
  `getRepositoryName(URL url)`
  Get the shared repository name associated with a repository URL or null if not applicable.
  `static boolean`
  `isGhidraURL(String str)`
  Determine if the specified string appears to be a possible ghidra URL (starts with "ghidra:/").
  `static boolean`
  `isGhidraURL(URL url)`
  Tests if the given url is using the Ghidra protocol
  `static boolean`
  `isLocalGhidraURL(String str)`
  Determine if URL string uses a local format (e.g., `ghidra:/path...`).
  `static boolean`
  `isLocalProjectURL(URL url)`
  Determine if the specified URL is a local project URL.
  `static boolean`
  `isServerRepositoryURL(URL url)`
  Determine if the specified URL is any type of server "repository" URL.
  `static boolean`
  `isServerURL(String str)`
  Determine if URL string uses a remote server format (e.g., `ghidra://host...`).
  `static boolean`
  `isServerURL(URL url)`
  Determine if the specified URL is any type of supported server Ghidra URL.
  `static boolean`
  `localProjectExists(URL url)`
  Determine if the specified URL refers to a local project and it exists.
  `static URL`
  `makeURL(ProjectLocator projectLocator)`
  Create a URL which refers to a local Ghidra project
  `static URL`
  `makeURL(ProjectLocator projectLocator, String projectFilePath, String ref)`
  Create a URL which refers to a Ghidra project with optional project file and ref.
  `static URL`
  `makeURL(String host, int port, String repositoryName)`
  Create a URL which refers to Ghidra Server repository and its root folder
  `static URL`
  `makeURL(String host, int port, String repositoryName, String repositoryPath)`
  Create a URL which refers to Ghidra Server repository content.
  `static URL`
  `makeURL(String host, int port, String repositoryName, String repositoryPath, String ref)`
  Create a URL which refers to Ghidra Server repository content.
  `static URL`
  `makeURL(String host, int port, String repositoryName, String repositoryFolderPath, String fileName, String ref)`
  Create a URL which refers to Ghidra Server repository content.
  `static URL`
  `makeURL(String dirPath, String projectName)`
  Create a URL which refers to a local Ghidra project
  `static URL`
  `makeURL(String projectLocation, String projectName, String projectFilePath, String ref)`
  Create a URL which refers to a local Ghidra project with optional project folder/file path and optional reference
  `static URL`
  `toURL(String projectPathOrURL)`
  Create a Ghidra URL from a string form of Ghidra URL or local project path.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### PROTOCOL

    public static final String PROTOCOL
    See Also:
      - Constant Field Values

  - ### MARKER_FILE_EXTENSION

    public static final String MARKER_FILE_EXTENSION
    See Also:
      - Constant Field Values

  - ### PROJECT_DIRECTORY_EXTENSION

    public static final String PROJECT_DIRECTORY_EXTENSION
    See Also:
      - Constant Field Values

- ## Method Details

  - ### localProjectExists

    public static boolean localProjectExists(URL url)
    Determine if the specified URL refers to a local project and it exists.
    Parameters:
      `url` - ghidra URL
    Returns:
      true if specified URL refers to a local project and it exists.

  - ### isGhidraURL

    public static boolean isGhidraURL(String str)
    Determine if the specified string appears to be a possible ghidra URL (starts with "ghidra:/").
    Parameters:
      `str` - string to be checked
    Returns:
      true if string is possible ghidra URL

  - ### isGhidraURL

    public static boolean isGhidraURL(URL url)
    Tests if the given url is using the Ghidra protocol
    Parameters:
      `url` - the url to test
    Returns:
      true if the url is using the Ghidra protocol

  - ### isLocalGhidraURL

    public static boolean isLocalGhidraURL(String str)
    Determine if URL string uses a local format (e.g., `ghidra:/path...`). Extensive validation is not performed. This method is intended to differentiate from a server URL only.
    Parameters:
      `str` - URL string
    Returns:
      true if string appears to be local Ghidra URL, else false

  - ### isServerURL

    public static boolean isServerURL(String str)
    Determine if URL string uses a remote server format (e.g., `ghidra://host...`). Extensive validation is not performed. This method is intended to differentiate from a local URL only.
    Parameters:
      `str` - URL string
    Returns:
      true if string appears to be remote server Ghidra URL, else false

  - ### isLocalProjectURL

    public static boolean isLocalProjectURL(URL url)
    Determine if the specified URL is a local project URL. No checking is performed as to the existence of the project.
    Parameters:
      `url` - ghidra URL
    Returns:
      true if specified URL refers to a local project (ghidra:/path/projectName...)

  - ### getProjectStorageLocator

    public static ProjectLocator getProjectStorageLocator(URL localProjectURL)
    Get the project locator which corresponds to the specified local project URL. Confirm local project URL with `isLocalProjectURL(URL)` prior to method use.
    Parameters:
      `localProjectURL` - local Ghidra project URL
    Returns:
      project locator or null if invalid path specified
    Throws:
      `IllegalArgumentException` - URL is not a valid `local project URL`.

  - ### getRepositoryName

    public static String getRepositoryName(URL url)
    Get the shared repository name associated with a repository URL or null if not applicable. For ghidra URL extensions it is assumed that the first path element corresponds to the repository name.
    Parameters:
      `url` - ghidra URL for shared project resource
    Returns:
      repository name or null if not applicable to URL

  - ### isServerRepositoryURL

    public static boolean isServerRepositoryURL(URL url)
    Determine if the specified URL is any type of server "repository" URL. No checking is performed as to the existence of the server or repository. NOTE: ghidra protocol extensions are not currently supported (e.g., ghidra:http://...).
    Parameters:
      `url` - ghidra URL
    Returns:
      true if specified URL refers to a Ghidra server repository (ghidra://host/repositoryNAME/path...)

  - ### isServerURL

    public static boolean isServerURL(URL url)
    Determine if the specified URL is any type of supported server Ghidra URL. No checking is performed as to the existence of the server or repository.
    Parameters:
      `url` - ghidra URL
    Returns:
      true if specified URL refers to a Ghidra server repository (ghidra://host/repositoryNAME/path...)

  - ### toURL

    public static URL toURL(String projectPathOrURL)
    Create a Ghidra URL from a string form of Ghidra URL or local project path. This method can consume strings produced by the getDisplayString method.
    Parameters:
      `projectPathOrURL` - project path (<absolute-directory>/<project-name>) or string form of Ghidra URL.
    Returns:
      local Ghidra project URL
    Throws:
      `IllegalArgumentException` - invalid path or URL specified
    See Also:
      - `getDisplayString(URL)`

  - ### getProjectURL

    public static URL getProjectURL(URL ghidraUrl)
    Get Ghidra URL which corresponds to the local-project or repository with any file path or query details removed.
    Parameters:
      `ghidraUrl` - ghidra file/folder URL (server-only URL not permitted)
    Returns:
      local-project or repository URL
    Throws:
      `IllegalArgumentException` - if URL does not specify the `ghidra` protocol or does not properly identify a remote repository or local project.

  - ### getProjectPathname

    public static String getProjectPathname(URL ghidraUrl)
    Get the project pathname referenced by the specified Ghidra file/folder URL. If path is missing root folder is returned.
    Parameters:
      `ghidraUrl` - ghidra file/folder URL (server-only URL not permitted)
    Returns:
      pathname of file or folder

  - ### getFolderURL

    public static URL getFolderURL(URL ghidraUrl)
    Force the specified URL to specify a folder. This may be neccessary when only folders are supported since Ghidra permits both a folder and file to have the same name within its parent folder. This method simply ensures that the URL path ends with a `/` character if needed.
    Parameters:
      `ghidraUrl` - ghidra URL
    Returns:
      ghidra folder URL
    Throws:
      `IllegalArgumentException` - if specified URL is niether a `valid remote server URL` or `local project URL`.

  - ### getNormalizedURL

    public static URL getNormalizedURL(URL url)
    Get a normalized URL which eliminates use of host names and optional URL ref which may prevent direct comparison.
    Parameters:
      `url` - ghidra URL
    Returns:
      normalized url

  - ### getDisplayString

    public static String getDisplayString(URL url)
    Generate preferred display string for Ghidra URLs. Form can be parsed by the toURL method.
    Parameters:
      `url` - ghidra URL
    Returns:
      formatted URL display string
    See Also:
      - `toURL(String)`

  - ### makeURL

    public static URL makeURL(String dirPath, String projectName)
    Create a URL which refers to a local Ghidra project
    Parameters:
      `dirPath` - absolute path of project location directory
      `projectName` - name of project
    Returns:
      local Ghidra project URL

  - ### makeURL

    public static URL makeURL(ProjectLocator projectLocator)
    Create a URL which refers to a local Ghidra project
    Parameters:
      `projectLocator` - absolute project location
    Returns:
      local Ghidra project URL
    Throws:
      `IllegalArgumentException` - if `projectLocator` does not have an absolute location

  - ### makeURL

    public static URL makeURL(String projectLocation, String projectName, String projectFilePath, String ref)
    Create a URL which refers to a local Ghidra project with optional project folder/file path and optional reference
    Parameters:
      `projectLocation` - absolute path of project location directory
      `projectName` - name of project
      `projectFilePath` - an absolute folder or file path within the project (e.g., /a/b/c, may be null)
      `ref` - optional location reference (may be null) which is appended to URL with a '#' delimiter.
    Returns:
      local Ghidra project URL
    Throws:
      `IllegalArgumentException` - if an absolute projectLocation path is not specified

  - ### makeURL

    public static URL makeURL(ProjectLocator projectLocator, String projectFilePath, String ref)
    Create a URL which refers to a Ghidra project with optional project file and ref. If project locator corresponds to a transient project a server URL form will be returned.
    Parameters:
      `projectLocator` - project locator (local or transient)
      `projectFilePath` - file path (e.g., /a/b/c, may be null)
      `ref` - location reference (may be null)
    Returns:
      local Ghidra project URL
    Throws:
      `IllegalArgumentException` - if invalid `projectFilePath` specified or if URL instantion fails.

  - ### makeURL

    public static URL makeURL(String host, int port, String repositoryName, String repositoryPath)
    Create a URL which refers to Ghidra Server repository content. Path may correspond to either a file or folder.
    Parameters:
      `host` - server host name/address
      `port` - optional server port (a value <= 0 refers to the default port)
      `repositoryName` - repository name
      `repositoryPath` - absolute folder or file path within repository. Folder paths should end with a '/' character.
    Returns:
      Ghidra Server repository content URL

  - ### makeURL

    public static URL makeURL(String host, int port, String repositoryName, String repositoryPath, String ref)
    Create a URL which refers to Ghidra Server repository content. Path may correspond to either a file or folder.
    Parameters:
      `host` - server host name/address
      `port` - optional server port (a value <= 0 refers to the default port)
      `repositoryName` - repository name
      `repositoryPath` - absolute folder or file path within repository.
      `ref` - ref or null Folder paths should end with a '/' character.
    Returns:
      Ghidra Server repository content URL

  - ### makeURL

    public static URL makeURL(String host, int port, String repositoryName, String repositoryFolderPath, String fileName, String ref)
    Create a URL which refers to Ghidra Server repository content. Path may correspond to either a file or folder.
    Parameters:
      `host` - server host name/address
      `port` - optional server port (a value <= 0 refers to the default port)
      `repositoryName` - repository name
      `repositoryFolderPath` - absolute folder path within repository.
      `fileName` - name of a file or folder contained within the specified `repositoryFolderPath`
      `ref` - optional URL ref or null Folder paths should end with a '/' character.
    Returns:
      Ghidra Server repository content URL
    Throws:
      `IllegalArgumentException` - if required arguments are blank or invalid

  - ### makeURL

    public static URL makeURL(String host, int port, String repositoryName)
    Create a URL which refers to Ghidra Server repository and its root folder
    Parameters:
      `host` - server host name/address
      `port` - optional server port (a value <= 0 refers to the default port)
      `repositoryName` - repository name
    Returns:
      Ghidra Server repository URL