Verified Owner
Top Description Fields Constructors Methods
org.jabref.logic.openoffice.oocsltext

public Class CSLCitationOOAdapter

extends Object
Class Inheritance
Imports
java.util.ArrayList, .Comparator, .Iterator, .LinkedHashMap, .LinkedHashSet, .List, .Map, .Optional, .SequencedSet, .StringJoiner, java.util.regex.Matcher, .Pattern, javafx.beans.value.ChangeListener, org.jabref.logic.citationstyle.CitationStyle, .CitationStyleGenerator, .CitationStyleOutputFormat, org.jabref.logic.openoffice.OpenOfficePreferences, .OpenOfficeReferenceMarkFormat, .ZoteroCitationLinker, org.jabref.logic.openoffice.style.OOStyle, org.jabref.model.database.BibDatabase, .BibDatabaseContext, org.jabref.model.entry.BibEntry, .BibEntryTypesManager, org.jabref.model.openoffice.ootext.OOFormat, .OOText, .OOTextIntoOO, org.jabref.model.openoffice.uno.CreationException, .NoDocumentException, com.sun.star.beans.XPropertySet, com.sun.star.container.NoSuchElementException, com.sun.star.lang.WrappedTargetException, com.sun.star.text.XTextCursor, com.sun.star.text.XTextDocument, com.sun.star.uno.Exception, com.sun.star.uno.UnoRuntime, com.sun.star.uno.XComponentContext, org.jspecify.annotations.NonNull, org.slf4j.Logger, .LoggerFactory
This class processes CSL citations in JabRef and interacts directly with LibreOffice using an XTextDocument instance. It is tightly coupled with CSLReferenceMarkManager for management of reference marks tied to the CSL citations. It uses OpenOfficePreferences to retrieve the initial style (last selected style), the bibliography title and its paragraph style. Any method in this class is NOT supposed to be moved (OR internally refactored without complete understanding - see implementation note).

Implementation Note

UNO API calls are expensive, and any additional operation slows down the net "macro-task" we are trying to achieve in the document. These "additional" operations may or may not be visible at the level of code in the form of additional function calls. In some cases, the same macro-task may be achieved by two different orders of actions, which may look semantically the same overall, but one order may result into more UNO API calls. For example, see the comment inside CSLCitationOOAdapter#insertCitation(XTextCursor, CitationStyle, List, BibDatabaseContext).

Field Summary

Modifier and TypeField and Description
private final BibEntryTypesManager
bibEntryTypesManager

private static final String
CITATION_DELIMITER

private static final Pattern
CITATION_NUMBER_PATTERN

private CSLCitationType
citationType

private final com.sun.star.uno.XComponentContext
componentContext

private List<BibDatabase>
currentSelectedDatabases

private CitationStyle
currentStyle

private final com.sun.star.text.XTextDocument
document

private static final CitationStyleOutputFormat
HTML_OUTPUT_FORMAT

private static final Logger
LOGGER

private final CSLReferenceMarkManager
markManager

private boolean
needsCSLReferenceMarkConversion

private final OpenOfficePreferences
openOfficePreferences

private final ChangeListener<Boolean>
zoteroCompatibilityModeListener

Constructor Summary

AccessConstructor and Description
public
CSLCitationOOAdapter(com.sun.star.text.XTextDocument doc, com.sun.star.uno.XComponentContext componentContext, OpenOfficePreferences openOfficePreferences, BibEntryTypesManager bibEntryTypesManager)

Method Summary

Modifier and TypeMethod and Description
private Map<String, Integer>
computeBibliographyOrderedCitationNumbers(CitationStyle selectedStyle, List<BibDatabase> selectedDatabases)

public void
convertReferenceMarksToPreference(List<BibDatabase> selectedDatabases)

private @NonNull String
createCitationText(CitationStyle style, List<BibEntry> entries, BibDatabaseContext unifiedBibDatabaseContext)

Helper method for creating citations for updateAllCitationsWithNewStyle and insertCitation.

private @NonNull String
createInTextCitationGroupText(CitationStyle style, List<BibEntry> entries, BibDatabaseContext bibDatabaseContext)

Helper method for creating citation group for insertInTextCitation and updateAllCitationsWithNewStyle

private @NonNull String
createInTextCitationText(CitationStyle style, BibEntry currentEntry, BibDatabaseContext bibDatabaseContext)

Helper method for creating in-text citations for updateAllCitationsWithNewStyle and insertInTextCitation.

public void
dispose()

public List<String>
getCitedCitationKeys()

private List<BibEntry>
getResolvedEntriesForMark(CSLReferenceMark mark, BibDatabase unifiedDatabase)

public void
insertCitation(com.sun.star.text.XTextCursor cursor, CitationStyle selectedStyle, List<BibEntry> entries, BibDatabaseContext currentEntryContext)

Inserts a citation for a group of entries.

public void
insertEmptyCitation(com.sun.star.text.XTextCursor cursor, CitationStyle selectedStyle, List<BibEntry> entries, BibDatabaseContext currentEntryContext)

Inserts "empty" citations for a list of entries at the cursor to the document.

public void
insertInTextCitation(com.sun.star.text.XTextCursor cursor, CitationStyle selectedStyle, List<BibEntry> entries, BibDatabaseContext currentEntryContext)

Inserts in-text citations for a group of entries.

public void
insertJabRefBibliography(com.sun.star.text.XTextCursor cursor, CitationStyle selectedStyle, List<BibEntry> entries, List<BibDatabase> selectedDatabases)

Creates a "Bibliography" section in the document and inserts a list of references.

private void
insertReferences(com.sun.star.text.XTextCursor cursor, List<BibEntry> entries, OOText ooText, CitationStyle selectedStyle, CSLCitationType citationType, BibDatabaseContext currentEntryContext)

Inserts references and also adds a space before the citation if not already present ("smart space").

public void
insertZoteroBibliography(com.sun.star.text.XTextCursor cursor, CitationStyle selectedStyle, List<BibEntry> entries, List<BibDatabase> selectedDatabases)

public boolean
isCitedEntry(BibEntry entry)

Checks if an entry has already been cited before in the document.

public void
linkZoteroCitations(BibDatabaseContext currentEntryContext)

public boolean
needsReferenceMarkConversion()

private List<BibEntry>
prepareBibliographyEntries(CitationStyle selectedStyle, List<BibEntry> entries, List<BibDatabase> selectedDatabases)

public void
prepareCitationInsertion(CitationStyle newStyle, CSLCitationType newCitationType, BibDatabaseContext currentEntryContext, List<BibDatabase> selectedDatabases)

public void
refreshCitationState()

private void
setCitationStyleParameters(CitationStyle newStyle, CSLCitationType newCitationType, List<BibDatabase> selectedDatabases)

This method is used to determine whether citation style and citation type should be updated.

private void
sortBibliographyEntriesByCurrentCitationNumbers(List<BibEntry> bibliographyEntries)

private void
sortBibliographyEntriesByPreferredCitationNumbers(List<BibEntry> bibliographyEntries, Map<String, Integer> citationKeyToNumber)

private void
updateAllCitationsWithNewStyle(CitationStyle style, CSLCitationType citationType, List<BibDatabase> selectedDatabases)

Ideally, the methods of this class are supposed to work with CSLReferenceMarkManager, and not CSLReferenceMark directly.

private void
updateNumericCitationsFromBibliographyOrder(CitationStyle selectedStyle, List<BibDatabase> selectedDatabases)

private String
updateSingleOrMultipleCitationNumbers(String citation, List<BibEntry> entries)

Transforms the numbers in the citation to globally-unique (and thus, reusable) numbers.

private void
writeBibliographyEntries(com.sun.star.text.XTextCursor cursor, CitationStyle selectedStyle, List<BibEntry> bibliographyEntries)

Writes bibliography entries using JabRef's standard CSL bibliography rendering.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

bibEntryTypesManagerback to summary
private final BibEntryTypesManager bibEntryTypesManager
CITATION_DELIMITERback to summary
private static final String CITATION_DELIMITER
CITATION_NUMBER_PATTERNback to summary
private static final Pattern CITATION_NUMBER_PATTERN
citationTypeback to summary
private CSLCitationType citationType
componentContextback to summary
private final com.sun.star.uno.XComponentContext componentContext
currentSelectedDatabasesback to summary
private List<BibDatabase> currentSelectedDatabases
currentStyleback to summary
private CitationStyle currentStyle
documentback to summary
private final com.sun.star.text.XTextDocument document
HTML_OUTPUT_FORMATback to summary
private static final CitationStyleOutputFormat HTML_OUTPUT_FORMAT
LOGGERback to summary
private static final Logger LOGGER
markManagerback to summary
private final CSLReferenceMarkManager markManager
needsCSLReferenceMarkConversionback to summary
private boolean needsCSLReferenceMarkConversion
openOfficePreferencesback to summary
private final OpenOfficePreferences openOfficePreferences
zoteroCompatibilityModeListenerback to summary
private final ChangeListener<Boolean> zoteroCompatibilityModeListener

Constructor Detail

CSLCitationOOAdapterback to summary
public CSLCitationOOAdapter(com.sun.star.text.XTextDocument doc, com.sun.star.uno.XComponentContext componentContext, OpenOfficePreferences openOfficePreferences, BibEntryTypesManager bibEntryTypesManager) throws com.sun.star.lang.WrappedTargetException, com.sun.star.container.NoSuchElementException

Method Detail

computeBibliographyOrderedCitationNumbersback to summary
private Map<String, Integer> computeBibliographyOrderedCitationNumbers(CitationStyle selectedStyle, List<BibDatabase> selectedDatabases)
convertReferenceMarksToPreferenceback to summary
public void convertReferenceMarksToPreference(List<BibDatabase> selectedDatabases) throws CreationException, com.sun.star.uno.Exception
createCitationTextback to summary
private @NonNull String createCitationText(CitationStyle style, List<BibEntry> entries, BibDatabaseContext unifiedBibDatabaseContext)

Helper method for creating citations for updateAllCitationsWithNewStyle and insertCitation.

createInTextCitationGroupTextback to summary
private @NonNull String createInTextCitationGroupText(CitationStyle style, List<BibEntry> entries, BibDatabaseContext bibDatabaseContext)

Helper method for creating citation group for insertInTextCitation and updateAllCitationsWithNewStyle

createInTextCitationTextback to summary
private @NonNull String createInTextCitationText(CitationStyle style, BibEntry currentEntry, BibDatabaseContext bibDatabaseContext)

Helper method for creating in-text citations for updateAllCitationsWithNewStyle and insertInTextCitation.

disposeback to summary
public void dispose()
getCitedCitationKeysback to summary
public List<String> getCitedCitationKeys() throws com.sun.star.lang.WrappedTargetException, com.sun.star.container.NoSuchElementException
getResolvedEntriesForMarkback to summary
private List<BibEntry> getResolvedEntriesForMark(CSLReferenceMark mark, BibDatabase unifiedDatabase)
insertCitationback to summary
public void insertCitation(com.sun.star.text.XTextCursor cursor, CitationStyle selectedStyle, List<BibEntry> entries, BibDatabaseContext currentEntryContext) throws CreationException, com.sun.star.uno.Exception

Inserts a citation for a group of entries. Comparable to LaTeX's \cite command.

insertEmptyCitationback to summary
public void insertEmptyCitation(com.sun.star.text.XTextCursor cursor, CitationStyle selectedStyle, List<BibEntry> entries, BibDatabaseContext currentEntryContext) throws CreationException, com.sun.star.uno.Exception

Inserts "empty" citations for a list of entries at the cursor to the document. Adds the entries to the list for which bibliography is to be generated.

insertInTextCitationback to summary
public void insertInTextCitation(com.sun.star.text.XTextCursor cursor, CitationStyle selectedStyle, List<BibEntry> entries, BibDatabaseContext currentEntryContext) throws CreationException, com.sun.star.uno.Exception

Inserts in-text citations for a group of entries. Comparable to LaTeX's \citet command.

Implementation Note

Very similar to the insertCitation method.

insertJabRefBibliographyback to summary
public void insertJabRefBibliography(com.sun.star.text.XTextCursor cursor, CitationStyle selectedStyle, List<BibEntry> entries, List<BibDatabase> selectedDatabases) throws com.sun.star.uno.Exception, CreationException

Creates a "Bibliography" section in the document and inserts a list of references. The list is generated based on the existing citations, in-text citations and empty citations in the document.

insertReferencesback to summary
private void insertReferences(com.sun.star.text.XTextCursor cursor, List<BibEntry> entries, OOText ooText, CitationStyle selectedStyle, CSLCitationType citationType, BibDatabaseContext currentEntryContext) throws CreationException, com.sun.star.uno.Exception

Inserts references and also adds a space before the citation if not already present ("smart space").

insertZoteroBibliographyback to summary
public void insertZoteroBibliography(com.sun.star.text.XTextCursor cursor, CitationStyle selectedStyle, List<BibEntry> entries, List<BibDatabase> selectedDatabases) throws com.sun.star.uno.Exception, CreationException
isCitedEntryback to summary
public boolean isCitedEntry(BibEntry entry)

Checks if an entry has already been cited before in the document. Required for consistent numbering of numeric citations - if present, the number is to be reused, else a new number is to be assigned.

linkZoteroCitationsback to summary
public void linkZoteroCitations(BibDatabaseContext currentEntryContext)
needsReferenceMarkConversionback to summary
public boolean needsReferenceMarkConversion() throws com.sun.star.lang.WrappedTargetException, com.sun.star.container.NoSuchElementException
prepareBibliographyEntriesback to summary
private List<BibEntry> prepareBibliographyEntries(CitationStyle selectedStyle, List<BibEntry> entries, List<BibDatabase> selectedDatabases) throws com.sun.star.uno.Exception, CreationException
prepareCitationInsertionback to summary
public void prepareCitationInsertion(CitationStyle newStyle, CSLCitationType newCitationType, BibDatabaseContext currentEntryContext, List<BibDatabase> selectedDatabases) throws CreationException, com.sun.star.uno.Exception
refreshCitationStateback to summary
public void refreshCitationState() throws com.sun.star.lang.WrappedTargetException, com.sun.star.container.NoSuchElementException
setCitationStyleParametersback to summary
private void setCitationStyleParameters(CitationStyle newStyle, CSLCitationType newCitationType, List<BibDatabase> selectedDatabases) throws CreationException, com.sun.star.uno.Exception

This method is used to determine whether citation style and citation type should be updated. Citation type and citation style are extracted into one method for more readability and uniformity.

sortBibliographyEntriesByCurrentCitationNumbersback to summary
private void sortBibliographyEntriesByCurrentCitationNumbers(List<BibEntry> bibliographyEntries)
sortBibliographyEntriesByPreferredCitationNumbersback to summary
private void sortBibliographyEntriesByPreferredCitationNumbers(List<BibEntry> bibliographyEntries, Map<String, Integer> citationKeyToNumber)
updateAllCitationsWithNewStyleback to summary
private void updateAllCitationsWithNewStyle(CitationStyle style, CSLCitationType citationType, List<BibDatabase> selectedDatabases) throws com.sun.star.uno.Exception, CreationException

Ideally, the methods of this class are supposed to work with CSLReferenceMarkManager, and not CSLReferenceMark directly. However, all "generation" of CSL style citations (via CitationStyleGenerator) occur in this class, and not in CSLReferenceMarkManager. Furthermore, CSLReferenceMarkManager is not composed of CitationStyle. Hence, we keep CSLReferenceMarkManager independent of CitationStyleGenerator and CitationStyle, and keep the following two methods here.

updateNumericCitationsFromBibliographyOrderback to summary
private void updateNumericCitationsFromBibliographyOrder(CitationStyle selectedStyle, List<BibDatabase> selectedDatabases) throws CreationException, com.sun.star.uno.Exception
updateSingleOrMultipleCitationNumbersback to summary
private String updateSingleOrMultipleCitationNumbers(String citation, List<BibEntry> entries)

Transforms the numbers in the citation to globally-unique (and thus, reusable) numbers.

writeBibliographyEntriesback to summary
private void writeBibliographyEntries(com.sun.star.text.XTextCursor cursor, CitationStyle selectedStyle, List<BibEntry> bibliographyEntries) throws com.sun.star.uno.Exception, CreationException

Writes bibliography entries using JabRef's standard CSL bibliography rendering.

Numeric styles without a bibliography sort keep first-appearance ordering. Numeric styles with a bibliography sort are preordered to the citeproc-emitted bibliography order so in-text numbers and bibliography numbers stay aligned. For non-numeric styles, ordering is left to the citeproc item data provider.