Module jonix.onix3
Package com.tectonica.jonix.onix3

Class Product

java.lang.Object
com.tectonica.jonix.onix3.Product
All Implemented Interfaces:
OnixComposite, OnixComposite.OnixSuperComposite, OnixProduct, OnixTag, Serializable
public class Product extends Object implements OnixProduct, Serializable

Product composite

A product is described by a group of data elements beginning with an XML label <Product> and ending with an XML label </Product>. The entire group of data elements which is enclosed between these two labels constitutes an ONIX Product record. The Product record is the fundamental unit within an ONIX Product Information message. In almost every case, each Product record describes an individually tradable item; and in all circumstances, each tradable item identified by a recognized product identifier should be described by one, and only one, ONIX Product record.

In ONIX 3.0 and later, a Product record has a mandatory ‘preamble’ comprising data Groups P.1 and P.2, and carrying data that identifies the record and the product to which it refers. This is followed by up to eight ‘blocks’, each of which is optional. Of these blocks, Blocks 1 to 5, plus 7 and 8 are not repeatable. Block 6 appears to be repeatable, but it is often more useful to think of a singular Block 6 comprising all repeats of its contained <ProductSupply> composites. In special circumstances – with partial (‘Block’) updates and only when <MarketReference> is used to label each individual <ProductSupply> composite – Block 6 can be thought of as a truly repeatable block, each repeat consisting of a single <ProductSupply> composite.

Reference name <Product>
Short tag <product>
Cardinality 0…n

This tag may be included in the following composites:

Possible placements within ONIX message:

See Also:

  • Field Details

  • Constructor Details

    • Product

      public Product(Element element)
      This constructor is for backward compatibility. For future proofing, it's recommended to use the other constructor, passing onixRelease label.

    • Product

      public Product(Element element, String onixRelease)

  • Method Details

    • onixVersion

      public OnixVersion onixVersion()
      Specified by:
      onixVersion in interface OnixProduct

    • onixRelease

      public String onixRelease()
      Specified by:
      onixRelease in interface OnixProduct

    • _initialize

      public void _initialize()
      Description copied from interface: OnixComposite
      This is an internal API. Since Jonix 8.0, composite objects are being populated lazily. This method initiates the population process, and is invoked internally by the accessor APIs of the composites
      Specified by:
      _initialize in interface OnixComposite

    • exists

      public boolean exists()
      Description copied from interface: OnixTag
      indicates whether this tag exists in the ONIX record
      Specified by:
      exists in interface OnixTag
      Returns:
      whether this tag (<Product> or <product>) is explicitly provided in the ONIX XML

    • ifExists

      public void ifExists(Consumer<Product> action)

    • getXmlElement

      public Element getXmlElement()
      Description copied from interface: OnixComposite
      For advanced use-cases only.
      Specified by:
      getXmlElement in interface OnixComposite
      Returns:
      native representation of the XML element underlying to this tag

    • recordReference

      public RecordReference recordReference()

      For every product, you must choose a single record reference which will uniquely identify the Information record which you send out about that product, and which will remain as its permanent identifier every time you send an update. It doesn’t matter what reference you choose, provided that it is unique and permanent. This record reference doesn’t identify the product – even though you may choose to use the ISBN or another product identifier as a part of your record reference – it identifies your information record about the product, so that the person to whom you are sending an update can match it with what you have previously sent. It is not recommended to use a product identifier as the whole of the record reference. A good way of generating references which are not part of a recognized product identification scheme but which can be guaranteed to be unique is to prefix a product identifier or a meaningless row ID from your internal database with a reversed Internet domain name which is registered to your organization (reversal prevents the record reference appearing to be a resolvable URL). Alternatively, use a UUID.

      This field is mandatory and non-repeating.

      Jonix-Comment: this field is required

    • notificationType

      public NotificationType notificationType()

      An ONIX code which indicates the type of notification or update which you are sending. Mandatory and non-repeating.

      Jonix-Comment: this field is required

    • productIdentifiers

      public ListOfOnixDataCompositeWithKey<ProductIdentifier,JonixProductIdentifier,ProductIdentifierTypes> productIdentifiers()

      A group of data elements which together specify an identifier of a product in accordance with a particular scheme. Mandatory within <Product>, and repeatable with different identifiers for the same product. As well as standard identifiers, the composite allows proprietary identifiers (for example SKUs assigned by wholesalers or vendors) to be sent as part of the ONIX record.

      ISBN-13 numbers in their unhyphenated form constitute a range of GTIN-13 numbers that has been reserved for the international book trade. Effective from 1 January 2007, it was agreed by ONIX national groups that it should be mandatory in an ONIX <Product> record for any item carrying an ISBN-13 to include the ISBN-13 labelled as a GTIN-13 number (ie as <ProductIDType> code 03), since this is how the ISBN-13 will be used in book trade transactions. For many ONIX applications this will also be sufficient.

      For some ONIX applications, however, particularly when data is to be supplied to the library sector, there may be reasons why the ISBN-13 must also be sent labelled distinctively as an ISBN-13 (ie as <ProductIDType> code 15). Users should consult ‘good practice’ guidelines and/or discuss with their trading partners.

      Note that for some identifiers such as ISBN, punctuation (typically hyphens or spaces for ISBNs) is used to enhance readability when printed, but the punctuation is dropped when carried in ONIX data. But for other identifiers – for example DOI – the punctuation is an integral part of the identifier and must always be included.

      Jonix-Comment: this list is required to contain at least one item

    • recordSourceType

      public RecordSourceType recordSourceType()

      An ONIX code which indicates the type of source which has issued the ONIX record. Optional and non-repeating, independently of the occurrence of any other field.

      Jonix-Comment: this field is optional

    • recordSourceName

      public RecordSourceName recordSourceName()

      The name of the party which issued the record, as free text. Optional and non-repeating, independently of the occurrence of any other field.

      Jonix-Comment: this field is optional

    • descriptiveDetail

      public DescriptiveDetail descriptiveDetail()

      The descriptive detail block covers data Groups P.3 to P.13, all of which are essentially part of the factual description of the form and content of a product. The block as a whole is non-repeating. It is mandatory in any <Product> record unless the <NotificationType> in Group P.1 indicates that the record is an update notice which carries only those blocks in which changes have occurred.

      Jonix-Comment: this field is optional

    • collateralDetail

      public CollateralDetail collateralDetail()

      The collateral detail block covers data Groups P.14 to P.17, all of which are primarily concerned with information and/or resources which in one way or another support the marketing of the product. The block as a whole is non-repeating.

      The block is not mandatory within the <Product> record, nor are any of the individual sections mandatory within an occurrence of the block. However, in most circumstances, the block should contain at least one instance of <TextContent>, <CitedContent>, <SupportingResource> or <Prize>. It may be empty only within a partial or ‘block update’ (Notification or update type 04, see P.1.2), when the intention is to remove all previously-supplied collateral material.

      Jonix-Comment: this field is optional

    • promotionDetail

      public PromotionDetail promotionDetail()

      The promotion detail block comprises the single data Group P.27. The block as a whole is optional and non-repeating, and is used only when there is a need to describe various promotional events intended to promote the product in a structured way. When used, the block usually consists of one or more instances of <PromotionalEvent>. It may be empty only within a partial or ‘block update’ (Notification or update type 04, see P.1.2), when the intention is to remove all previously-supplied promotion detail.

      Jonix-Comment: this field is optional

    • contentDetail

      public ContentDetail contentDetail()

      The Content detail block comprises the single data Group P.18. The block as a whole is non-repeating. It is not mandatory within the <Product> record, and is used only when there is a requirement to describe individual chapters or parts within a product in a fully structured way. The more usual ONIX practice is to send a table of contents as text, possibly in XHTML, in Group P.14.

      When used, the block should normally contain at least one instance of <ContentItem>. It may be empty only within a partial or ‘block update’ (Notification or update type 04, see P.1.2), when the intention is to remove all previously-supplied content detail.

      Jonix-Comment: this field is optional

    • publishingDetail

      public PublishingDetail publishingDetail()

      The publishing detail block covers data Groups P.19 to P.21, carrying information on the publisher(s), ‘global’ publishing status, and rights attaching to a product. The block as a whole is non-repeating. It is mandatory in any <Product> record unless the <NotificationType> in Group P.1 indicates that the record is an update notice which carries only those blocks in which changes have occurred.

      Jonix-Comment: this field is optional

    • relatedMaterial

      public RelatedMaterial relatedMaterial()

      The related material block covers data Groups P.22 and P.23, providing links to related works and related products. The block as a whole is optional and non-repeating.

      None of the individual sections are mandatory within an occurrence of the block. However, in most circumstances, the block should contain at least one instance of <RelatedWork> or <RelatedProduct>. It may be empty only within a partial or ‘block update’ (Notification or update type 04, see P.1.2), when the intention is to remove all previously-supplied information about related works and products.

      Jonix-Comment: this field is optional

    • productionDetail

      public ProductionDetail productionDetail()

      The Production detail block comprises the single data Group P.28. The block as a whole is non-repeating. It is optional within the <Product> record, and is used only when there is a requirement to communicate specification and file manifest detail relating to intermediary services within the supply chain, for example manufacturing on demand, e‑book conversion services or distribution of digital audio. It is not expected to be present in most ONIX messages – though recipients not requiring the data should be able to ignore the entire block if it is supplied.

      When used, the block should normally contain at least one instance of <ProductionManifest>. It may be empty only within a partial or ‘block update’ (Notification or update type 04, see P.1.2), when the intention is to remove all previously-supplied manifest detail.

      Jonix-Comment: this field is optional

    • deletionTexts

      public ListOfOnixElement<DeletionText,String> deletionTexts()

      Free text which indicates the reason why an ONIX record is being deleted. Optional and repeatable, and may occur only when the <NotificationType> element carries the code value 05. The language attribute is optional for a single instance of <DeletionText>, but must be included in each instance if <DeletionText> is repeated. Note that it refers to the reason why the record is being deleted, not the reason why a product has been ‘deleted’ (in industries which use this terminology when a product is withdrawn).

      A product cancellation or abandonment prior to publication, or a product becoming unavailable (eg as a result of being Out of print) are changes of <PublishingStatus> or of <ProductAvailability>, not reasons for deletion.

      Jonix-Comment: this list may be empty

    • recordSourceIdentifiers

      public ListOfOnixDataCompositeWithKey<RecordSourceIdentifier,JonixRecordSourceIdentifier,NameIdentifierTypes> recordSourceIdentifiers()

      A group of data elements which together define an identifier of the organization which is the source of the ONIX record. Optional, and repeatable in order to send multiple identifiers for the same organization.

      Jonix-Comment: this list may be empty

    • barcodes

      public ListOfOnixDataComposite<Barcode,JonixBarcode> barcodes()

      A group of data elements which together specify a barcode type and its position on a product. Optional: expected to be used only in North America. Repeatable if more than one type of barcode is carried on a single product. The absence of this composite does not mean that a product is not bar-coded.

      Jonix-Comment: this list may be empty

    • productSupplys

      public ListOfOnixComposite<ProductSupply> productSupplys()

      The product supply block covers data Groups P.24 to P.26, specifying a market, the publishing status and representation detail of the product in that market, and the supply arrangements for the product in that market. The <ProductSupply> composite is repeatable within the block to describe multiple markets. At least one occurrence is expected in a <Product> record unless the <NotificationType> in Group P.1 indicates that the record is a partial update notice which carries only those blocks in which changes have occurred.

      Note that for many products with simple supply arrangements and a single market, many details of that market are ‘inherited’ from Block 4 and need not be repeated.

      Jonix-Comment: this list may be empty