CFD Developer's Guide.

Table of contents.

Building a Comprobante.
Implementing a new version of the standard.
Module initialization.
Library customization.

1. Building a `Comprobante`.

A new Comprobante is generated by means of the following procedure:

Request.
A request for a Comprobante is required for this task and such a request is implemented by the CFDIBuildRequest.

The request contains details such as:
- the document that the Comprobante being requested will represent,
- the type of Comprobante,
- the version of Comprobante,
as well as any other data needed for the type of Comprobante being requested.
Instantiation.
A Comprobante is modeled by the IComprobante interface. A new instance is obtained by calling CFDService.newCFD( request ) with the request previously discussed.
Determiners are used to obtain/calculate the values from the IDocument instance that the new IComprobante represents.
Preparation.
The Comprobante instance built by the CFD service must be prepared for certification.
Certification.
Certify the CFDI,
XML file.
The certification process results in a XML stucture which represents the certified Comprobante. This sturcture is saved to file storage by means of the CFDIFileManager service.
Print file.
Finally, a human readable representation of the certified Comprobante is generated. The PDF file format is commonly used to produce such a representation but other formats could be used as well.
Delivery.
Both the XML and print files of the Comprobante are delivered to the customer via e-mail.

Code example for building a new sale invoice (i.e. ingreso):

         IComprobante     comprobante;
         CFDIIssuer       issuer;
         CFDModule        module;
         ICFDProcessor    processor;
         CFDIBuildRequest request;
         CFDService       service;

         request          = new CFDIBuildRequest();
         request.doc      = getDocument();
         request.issuer   = issuer;
         request.testMode = true;
         request.type     = CFDType.INGRESO;
         request.version  = CFDVersion.v4_0;

         module      = CFDSCut.getModule();
         service     = module.getCFDService();
         comprobante = service.newCFDI( request );

         processor.prepare( cfdi );
         processor.certify( cfdi );

         save( cfdi );
         exportPDF( cfdi );

2. Implementing a new version of the standard.

The methodology for implementing a new version of the Comprobante is described in this section.

2.1 JAXB library,
2.2 Wrapper classes (IComprobante),
2.3 Factory (ICFDFactory),
2.3 Generator (IGenerator),
2.4 Determiner (ICFDDeterminer),
2.5 Configuration (hard coded),
2.6 Configuration,
2.7 Stylesheets,

1.1 JAXB library.

The JAXB library allows reading and writing Comprobantes of the version being implemented. This library is automatically generated using the tools provided with the JDK as part of the Java Architecture for XML Binding (JAXB)implementation.

Details on the procedure to generate the library is explained in the Javadoc of each library, for example jlib_sat_cfd_40_jaxb_doc.jar.

Not all data types are defined in the XSD file. Those not included may require manual implementation, should it result useful.

2.2 Schema.

Each publication of the standard includes two files:

XML schema definition (XSD),
allows conversion of a Comprobante from its XML representation to the corresponding Java class, validation, etc.
an Extensible Stylesheet Language Transformation (XSLT);
required to generate the cadena original as specified in section E "Secuencia de formación para generar la cadena original".

Both XSD and XSLT files are integrated into the system as follows:

A CFDModule property.
represented by a constant of the interface CFDProperty named jcs_cfd_xx_xsd_tt where xx is the version of the standard (33, 40, and so on), and tt type type (public and local); and their value specified in the corresponding configuration file (XML) of the module.
Integration into the IGenerator.
a generator for the new version is explained below and it is where these files are loaded and used.

2.3 Interfaces.

Identify the elements and attributes introduced, removed, and modified by the new standard.

Comprobante elements added and modified by the standard are defined by means of interfaces. Provided that an element has not dropped or renamed any attributes defined by the previous version of the standard, elements that were already defined by the previous version and that contain new attributes may extend the corresponding interface implemented as part of the previous version.

Classes implementing the interfaces described by the previous paragraph must next be declared. These are wrapper classes that isolate the specifics of the library generated from the XML schema of the standard (i.e. JAXB, etc.) and further facilitates the process of integrating those classes into JCS CFD framework. One wrapper class is required for each element of the standard.

The following elements are required to suppor the new version:

factory (interface: ICFDIFactory),
generator (subclass of JAXBGenerator),
determiner (interface: ICFDDeterminer),

Add the new version to the CFD module: CFDModule.add( CFDVersion, ICFDIFactory ) CFDModule.add( CFDVersion, IGenerador ) via the GeneratorBuilder

2.4 Wrapper classes.

Other than during the parsing stage, the CFDModule does not manipulate JAXB objects directly. Instead, it manipulates Comprobantes wrapper classes, which are classes implementing IComprobante and related interfaces.

Examples are the conversion of:

a JAXB instance of cPais into/from a ICountry,
a JAXB instance of cUsoFCDI into/from a UsoCFD40.
etc.

2.5 Factory.

A factory is required by the processor to instantiate the Comprobante elements of the new implementation.

2.5 Generator.

The first implementation of the standard was 3.2 and was based on XML Beans. When the standard 3.3 was implemented, there was an issue with XMBL and JAXB was used instead.

As a result the design was changed to isolate the code as much as possible from the underlying technology. So there is a JAXB implementation of the generator and as long as JAXB is being used, all that is needed to add support for the new version is a class that configures the generator to use it (see JAXBGenerator33Build and JAXBGenerator40Build.

In fact, both JAXBGenerator33 and JAXBGenerator40 classes could be removed by relocating their factory methods (newXXX) to the corresponding ICFDIFactory33 factory implementation and using this factory instance from JAXBGenerator (if and when time allows).

2.5 Supporting classes.

Depending on the changes on the schema of the new version, the following classes may or may not require to be extended:

Factory
CFDIRequest

2.5 Configuration (hard coded).

Part of adding a new version is still hard coded. It is as follows

CFDModule.loadProcessor
a new version is added by this method with the call to CFDModule.add( CFDVersion )

todo: add schema illustrating the IDocframework, the XML realm (to parse and generate XML document), and how these two elements interact with each other.

3. Module initialization.

This section gives perspective on how the module is initialized and thus how the different elements are configured and initalizaed.

Processor initialization (class ProcessorInit).

Generator initialization (Generator33Build and Generator40Build).

4. Library customization.

This library has been designed to allow its customization by means extending some of its classes and/or implementing interfaces and defining the FQCN of your custom class via the approrpiate module properties.

Interface.	Reference implementation.	Property.
`ICEDeterminer`	`DetCE`	pending (instantiated in `CEFactory.newDeterminer`)
`IDetMercancia`	`DetMercancia`	pending (instantiated in `DetCe.DetCE()`