Package sk.iway.iwcm.doc

Class PlannedAssetPaths

java.lang.Object
sk.iway.iwcm.doc.PlannedAssetPaths
public final class PlannedAssetPaths extends Object
Maps files and folders between a page's protected planned directory and their public paths.

For example, page 42 stages /images/photo.webp at /files/protected/planned-changes/42/images/photo.webp. These helpers rewrite paths and validate their syntax and destinations without accessing the filesystem.

  • Field Details

  • Method Details

    • rewrite

      public static String rewrite(String value, int docId)
      Replaces a page's planned asset prefix with the public root in URLs or page content.

      This literal replacement preserves surrounding HTML, URL encoding, query strings and fragments. It does not validate paths or change prefixes belonging to other pages.

      Parameters:
      value - URL or content containing planned asset references; may be null
      docId - page ID identifying the planned prefix to replace
      Returns:
      content with each matching prefix replaced by /, or null for null input

    • containsPlannedPath

      public static boolean containsPlannedPath(String value)
      Detects a planned-directory reference anywhere in a URL or text.

      The check decodes URL escapes and ignores case. If decoding fails, it checks for planned-changes in the original text so malformed references still receive access checks. A match does not mean the path or page ID is valid.

      Parameters:
      value - URL or text to inspect; may be null
      Returns:
      true if a planned-directory reference is detected; false for null input

    • localPath

      public static String localPath(String value)
      Extracts and decodes a root-relative path while rejecting unsafe path syntax.

      Query strings and fragments are discarded, URL escapes are decoded as UTF-8, and literal + characters are preserved. The path must start with / and must not contain traversal segments, backslashes, repeated slashes, semicolons, remaining percent signs, control characters, or segments ending in a dot or space.

      A URL's scheme and authority are ignored. This method does not verify the origin, require a planned prefix, check permissions or inspect the filesystem.

      Parameters:
      value - non-null path or URL; literal spaces are accepted
      Returns:
      decoded root-relative path, suitable for directory permission checks
      Throws:
      IllegalArgumentException - if the URI is malformed, has no path, or has unsafe path syntax

    • getPublicPath

      public static String getPublicPath(String plannedPath, int docId)
      Resolves a planned file or folder to the public path used when publishing its page.

      For example, /files/protected/planned-changes/42/images/photo.webp becomes /images/photo.webp when docId is 42. The source is decoded and checked by localPath(String), its page ID must match docId, and the resulting public path must pass validatePublicPath(String). No files are copied or modified.

      Parameters:
      plannedPath - non-null planned asset path or URL
      docId - ID of the page whose planned directory must contain the asset, not a user ID
      Returns:
      decoded public path without the planned prefix, query string or fragment
      Throws:
      IllegalArgumentException - if the source path is invalid, belongs to another page, or maps to an unsupported public destination

    • removePlannedPrefix

      public static String removePlannedPrefix(String value)
      Converts a planned file or folder reference to its validated public path.

      The owning page ID is read from the path. Planned references are decoded and lose their URL authority, query string and fragment. Values without a planned reference are returned unchanged, without validation.

      Parameters:
      value - path or URL to convert; may be null
      Returns:
      validated public path for a planned reference, or the original value otherwise
      Throws:
      IllegalArgumentException - if a detected planned reference has an invalid path, page ID or public destination

    • rewriteToProtectedFolder

      public static String rewriteToProtectedFolder(int docId, String target)
      Prepends a page's protected planned-directory prefix to a public file or folder path.

      For example, page 42 and /files/catalog.pdf produce /files/protected/planned-changes/42/files/catalog.pdf. The decoded target is validated, but the original target is appended unchanged, preserving its URL encoding, query string and fragment. No directories are created.

      Parameters:
      docId - page ID to place in the prefix; expected to be positive but not validated here
      target - non-null root-relative public file or folder path
      Returns:
      protected planned path containing the page ID and the original target
      Throws:
      IllegalArgumentException - if the target has invalid path syntax or an unsupported destination