Lỗi kết xuất và I/O

Phạm vi

Các mục này bao quát các ngoại lệ kết xuất và vào/ra (I/O) được nêu ra trong khi quy trình HTML bố cục nội dung, trình phân giải paged-media gán hình học trang, trình định hình văn bản xử lý các hệ chữ phức tạp, giai đoạn kiểu chữ ngắt dòng, trình ghi tuần tự hóa một tài liệu, trình đọc phân tích một PDF hiện có, và giai đoạn siêu dữ liệu đọc một gói Extensible Metadata Platform (XMP).

Hai phân cấp cơ sở xuất hiện bên dưới, và sự khác biệt chi phối loại dữ liệu chẩn đoán mà bạn có thể đọc sau một catch:

• NextPdfException hiện thực ContextAwareExceptionInterface::getContext(): array. Bản hiện thực cơ sở trả về một mảng rỗng; một lớp con chỉ mang các khóa có cấu trúc khi nó ghi đè getContext(). Các lớp con không ghi đè nó vẫn phơi bày dữ liệu của chúng qua các thuộc tính public readonly.
• Một số lớp ở đây mở rộng trực tiếp RuntimeException của PHP. Chúng không nhận biết context và không có phương thức getContext(); hãy đọc getMessage() và bất kỳ thuộc tính công khai nào thay thế.

Mỗi mục nêu tên lớp chính xác, điều kiện trigger, các khóa context hoặc thuộc tính công khai mà nó mang theo, và đường khôi phục.

Bố cục HTML và paged media

UnsplittableContentException

• Khi nào nó được ném. Engine bố cục HTML nêu cái này khi nội dung được đánh dấu break-inside: avoid (một ô bảng có ràng buộc ngắt là Avoid) có một chiều cao đo được vượt quá chiều cao khả dụng của một trang đơn. Engine không thể thỏa mãn cả ràng buộc tránh-ngắt lẫn ranh giới trang, nên nó thất bại thay vì âm thầm tràn.
• Dữ liệu mang theo. Mở rộng NextPdfException nhưng không ghi đè getContext(), nên getContext() trả về một mảng rỗng. Dữ liệu chẩn đoán nằm trên các thuộc tính public readonly: gridRow (int), gridCol (int), contentHeight (float, điểm), và pageHeight (float, điểm). Thông báo nêu tên tọa độ ô và cả hai chiều cao.
• Khôi phục. Gỡ ràng buộc break-inside: avoid trên ô gây lỗi, giảm nội dung của ô để nó vừa một trang, hoặc tăng kích thước trang hoặc giảm lề của nó để chiều cao khả dụng chứa được nội dung.

BudgetExceededException

• Khi nào nó được ném. Các primitive bố cục chế-độ-retained nêu cái này khi một trong bốn tier ngân-sách-tài-nguyên được định nghĩa trong bản ghi quyết định kiến trúc ADR-020 bị vượt và caller chọn một thất bại cứng thay vì phương án dự phòng mềm. Đường mặc định không ném: ContainerLayout::acceptChild() trả về false, caller dự phòng về bố cục block, và một cảnh báo được phát ra. Ngoại lệ này dành cho xác thực tại-thời-điểm-cấu-hình và cho các test khẳng định bộ-ba vi phạm chính xác. Các tier là per-child (một child stream đã ghi vượt quá giới hạn của nó), per-container (ngân sách số-nút Tier 1), per-document (ngân sách lượt-bố-cục hoặc độ-sâu-lồng), và global (trần resident-set-size đỉnh 256 MB trên toàn SDK).
• Dữ liệu mang theo. Ghi đè getContext(), vốn trả về một hình dạng tám-khóa ổn định được công cụ giám sát hiệu năng ứng dụng (APM) tiêu thụ: budgetTier, exceededValue, budgetLimit, containerType, phase, breachOrigin, captureSize, và processedItemCount. Bốn khóa đầu là tập con v1.0.0 ban đầu và luôn được điền; bốn khóa sau mặc định là null hoặc 0 khi constructor được gọi không có chúng. getCausalWarningCode() ánh xạ bộ-ba (tier, container-type) tới WarningCode mà đường dự-phòng-mềm sẽ phát ra.
• Khôi phục. Với một vi phạm cấu hình, hạ giá trị được yêu cầu trở lại vào envelope đã lập tài liệu (ví dụ, ngân sách nút retained chấp nhận 5.000 tới 100.000 qua Config::withRetainedNodeBudget()). Với một vi phạm nội dung, giảm độ lồng container hoặc số nút, hoặc dựa vào phương án dự-phòng-mềm mặc định về bố cục block thay vì chọn bề mặt thất-bại-cứng.

UnsupportedNamedPageException

• Khi nào nó được ném. Giai đoạn paged-media nêu cái này, thất-bại-theo-hướng-đóng, khi một tài liệu khai báo một quy tắc @page <ident> { … } có tên (gắn vào nội dung qua thuộc tính page: <ident>). Các trang có tên từ CSS Paged Media Level 3 §3.4 và Level 4 §3.2 — bao gồm các pseudo-class :first, :left, :right, và :blank cùng các ghi đè size: và rotate: có tên — được phân tích nhưng không đường bố cục sản xuất nào tiêu thụ chúng. Engine từ chối thay vì phát ra việc phân trang mặc định sai-một-cách-âm-thầm mà việc bỏ qua quy tắc sẽ tạo ra.
• Dữ liệu mang theo. Ghi đè getContext(), vốn trả về page_names (danh sách các ident riêng biệt đã kích hoạt lỗi, theo thứ tự nguồn), has_size_override (bool), has_rotate_override (bool), và has_pseudo_classes (bool). Cùng các giá trị đó được phơi bày trên các thuộc tính công khai pageNames, hasSizeOverride, hasRotateOverride, và hasPseudoClasses.
• Khôi phục. Gỡ các quy tắc @page <ident> có tên và mọi ràng buộc page: <ident>, và diễn đạt hình học mong muốn qua quy tắc @page { … } không-tên được hỗ trợ và các dạng pseudo-class của nó. Hoặc, ghim vào một bản phát hành tương lai có triển khai hỗ trợ bố cục trang-có-tên đầy đủ.

Kiểu chữ và định hình văn bản

IcuRequirementException

• Khi nào nó được ném. Phân đoạn văn bản nêu cái này khi nó cần trình lặp ngắt dòng International Components for Unicode (ICU) nhưng chính sách yêu-cầu-ICU đang hoạt động (NEXTPDF_REQUIRE_ICU=1) trong khi tiện ích ext-intl và IntlBreakIterator không có sẵn.
• Dữ liệu mang theo. Mở rộng trực tiếp RuntimeException, nên nó không nhận biết context và không có getContext(). Nó là một tinh chỉnh nghiêm ngặt của ngoại lệ chung mà cùng đường mã đã ném trước đây, nên các trình xử lý catch (\RuntimeException) hiện có tiếp tục hoạt động.
• Khôi phục. Cài đặt và bật ext-intl để trình ngắt ICU có sẵn, hoặc bỏ đặt NEXTPDF_REQUIRE_ICU để dự phòng về trình phân đoạn không-ICU nơi chính sách yêu-cầu-ICU không bắt buộc.

ScriptShaperException

• Khi nào nó được ném. Đây là ngoại lệ cơ sở cho giao diện nhà cung cấp dịch vụ định-hình-hệ-chữ (SPI). Hôm nay nó không được ném trực tiếp; các kiểu con cụ thể được ném thay thế. Bắt kiểu này để xử lý mọi lỗi định hình ở một nơi.
• Dữ liệu mang theo. Mở rộng trực tiếp RuntimeException; không nhận biết context, không có getContext().
• Khôi phục. Rẽ nhánh theo kiểu con cụ thể. Xem NotYetImplementedException bên dưới để biết kiểu con duy nhất được cung cấp trong bản phát hành hiện tại.

NotYetImplementedException

• Khi nào nó được ném. Mọi trình định-hình-hệ-chữ giữ-chỗ nêu cái này từ thân shape() của nó cho các hệ chữ có việc định hình cụ thể bị hoãn (Mông Cổ và Tây Tạng). Seam SPI định hình đã sẵn-sàng-về-kiến-trúc, nhưng định hình thực còn chờ một fixture được người-bản-ngữ xác nhận. Nêu ra một ngoại lệ thay vì một no-op âm thầm sẽ phơi bày việc đấu nối sản xuất vô tình tại môi trường chạy thay vì phát ra văn bản chưa định hình vào một PDF tuyên bố khả năng truy cập được gắn thẻ.
• Dữ liệu mang theo. Mở rộng ScriptShaperException (và do đó RuntimeException), nên nó không nhận biết context và không có getContext(). Dữ liệu chẩn đoán nằm trên các thuộc tính public readonly của nó: bcp47LanguageTag (thẻ BCP-47 của đoạn chạy, như mn-Mong hoặc bo-Tibt) và missingCapability (năng lực cụ thể mà bản hiện thực còn thiếu). Thông báo bao gồm cả hai.
• Khôi phục. Đừng định tuyến các đoạn chạy ở các hệ chữ chưa-hiện-thực qua trình định hình trong sản xuất. Phát hiện thẻ ngôn ngữ ở phía trên và hoặc dự phòng về một đường kết xuất khác hoặc ghim vào một bản phát hành tương lai có triển khai định hình cho hệ chữ bị ảnh hưởng.

Profile output của trình ghi và mã hóa

Pdf14FeatureRejectedException

• Khi nào nó được ném. Trình ghi nêu cái này khi một tài liệu chứa một tính năng bị cấm dưới profile output PDF 1.4 (ISO 19005-1:2005 / PDF/A-1), vốn cấm các cấu trúc được giới thiệu ở các phiên bản PDF sau.
• Dữ liệu mang theo. Mở rộng NextPdfException nhưng không ghi đè getContext(), nên getContext() trả về một mảng rỗng. Dữ liệu chẩn đoán nằm trên các thuộc tính public readonly của nó: feature (tên tính năng bị từ chối), reason (lý do nó bị cấm), và isoClause (tham chiếu điều khoản ISO). Thông báo kết hợp cả ba.
• Khôi phục. Gỡ hoặc thay tính năng bị từ chối bằng một tương đương tương thích-PDF-1.4, hoặc nhắm tới một profile output cao hơn cho phép tính năng.

Pdf20FeatureRejectedException

• Khi nào nó được ném. Trình ghi nêu cái này khi một tài liệu chứa một tính năng bị cấm dưới profile output PDF 2.0 nghiêm ngặt. ISO 32000-2:2020 phế bỏ các cấu trúc mà PDF 1.7 vẫn cho phép — đáng chú ý nhất là các phông Standard 14 Type 1 (§9.6.2), vốn phải được nhúng trong một tài liệu PDF 2.0 hợp khuôn.
• Dữ liệu mang theo. Cùng hình dạng với Pdf14FeatureRejectedException: mở rộng NextPdfException, không ghi đè getContext() (trả về một mảng rỗng), và phơi bày feature, reason, và isoClause dưới dạng các thuộc tính public readonly.
• Khôi phục. Khắc phục tính năng bị từ chối — ví dụ, nhúng các phông base 14 — hoặc dùng cửa thoát đã được lập tài liệu khi có (cho các phông base 14 không-nhúng, Document::allowNonEmbeddedBase14()).

PublicKeyEncryptionUnsupportedException

• Khi nào nó được ném. PdfWriter::build() nêu cái này tại điểm vào khi encryptionMode của tài liệu là pubkey (một danh sách người nhận khóa-công-khai) trước khi việc điều phối mã hóa thân-stream khóa-công-khai phía-trình-ghi được đấu nối. Từ chối ngay từ đầu ngăn việc âm thầm phát ra một PDF không-mã-hóa mà caller tưởng là đã được mã hóa.
• Dữ liệu mang theo. Mở rộng trực tiếp RuntimeException, nên nó không nhận biết context và không có getContext(). Nó là một tinh chỉnh nghiêm ngặt của ngoại lệ chung mà cùng vị trí đã ném trước đây, nên các trình xử lý catch (\RuntimeException) hiện có tiếp tục hoạt động.
• Khôi phục. Dùng một chế độ mã hóa được hỗ trợ (mã hóa dựa trên mật khẩu) thay vì danh sách người nhận khóa-công-khai, hoặc ghim vào một bản phát hành có triển khai hỗ trợ mã hóa khóa-công-khai. Đừng coi output là đã được mã hóa khi cái này được ném.

Đầu vào trình đọc và siêu dữ liệu

UnsupportedPdfStructureException

• Khi nào nó được ném. Trình đọc object-graph nêu cái này, thất-bại-theo-hướng-đóng, khi một PDF đầu vào nằm ngoài envelope được hỗ trợ của nó. Trình đọc hỗ trợ các bảng cross-reference cổ điển (ISO 32000-2:2020 §7.5.4), các cross-reference stream (§7.5.8), các đối tượng nén-object-stream (§7.5.7), các chuỗi /Prev đa-revision (§7.5.6), và các tệp hybrid-reference qua /XRefStm (§7.5.8.4). Bất kỳ thứ gì ngoài envelope đó đều phơi bày ngoại lệ này thay vì một lần phân tích một-phần hoặc đoán. Các constructor có tên ánh xạ tới các trường hợp lý do: encrypted(), damagedCrossReference(), cyclicReferenceChain(), nonConformantObjectStream(), irresolvableObjectCollision(), truncatedFile(), và crossReferenceOffsetOutOfBounds().
• Dữ liệu mang theo. Mở rộng trực tiếp RuntimeException, nên nó không nhận biết context và không có getContext(). Nó phơi bày một thuộc tính public readonly reason kiểu UnsupportedPdfStructureReason (một enum) nên các caller rẽ nhánh theo loại chính xác mà không phân tích thông báo; một chuỗi detail tùy chọn và một throwable previous có thể thêm context có giới hạn, không nhạy cảm. Thông báo mặc định là tóm tắt không-rò-rỉ của lý do.
• Khôi phục. Rẽ nhánh theo reason. Với EncryptedDocument, chạy một bước giải mã trước khi đọc, vì giải mã nằm ngoài phạm vi của trình đọc. Với DamagedCrossReference, TruncatedFile, hoặc CrossReferenceOffsetOutOfBounds, coi tệp là hỏng khuôn hoặc không đầy đủ và lấy lại hoặc sửa nguồn. Với CyclicReferenceChain, NonConformantObjectStream, hoặc IrresolvableObjectCollision, đầu vào vi phạm mô hình cấu trúc và không thể được đọc như hiện trạng.

PacketTooLargeException

• Khi nào nó được ném. Trình đọc siêu dữ liệu XMP theo luồng nêu cái này khi một gói XMP nhúng vượt quá trần byte được cấu hình. Nó là một bộ bảo vệ phòng thủ chống các đầu vào kiểu entity-expansion và quadratic-blowup (một trần đỉnh 128 MB chống lại XMP nhúng quy mô gigabyte).
• Dữ liệu mang theo. Mở rộng NextPdfException nhưng không ghi đè getContext(), nên getContext() trả về một mảng rỗng. Dữ liệu chẩn đoán nằm trên các thuộc tính public readonly của nó: byteCount (số byte quan sát được) và cap (giới hạn được cấu hình tính theo byte). Thông báo báo cáo cả hai.
• Khôi phục. Từ chối hoặc bỏ qua siêu dữ liệu quá khổ như là độc hại hoặc hỏng khuôn. Nếu một tài liệu chính đáng thực sự cần một gói lớn hơn, hãy nâng giới hạn được cấu hình một cách có chủ đích, cân nhắc rủi ro cạn-kiệt-bộ-nhớ mà bộ bảo vệ tồn tại để ngăn chặn.

Xem thêm

• Chỉ mục tài liệu tham khảo lỗi
• Khắc phục sự cố phông chữ và gắn thẻ — cho các triệu chứng NotYetImplementedException, ScriptShaperException, và IcuRequirementException.
• Khắc phục sự cố xác thực PDF/A và PDF/UA — cho các triệu chứng Pdf14FeatureRejectedException và Pdf20FeatureRejectedException.
• Khắc phục sự cố mã hóa và quyền — cho PublicKeyEncryptionUnsupportedException và lý do EncryptedDocument của trình đọc.