{"id":27881803,"url":"https://github.com/src-d/siva-java","last_synced_at":"2025-05-05T05:05:19.625Z","repository":{"id":57743247,"uuid":"99225077","full_name":"src-d/siva-java","owner":"src-d","description":"siva format implemented in Java","archived":false,"fork":false,"pushed_at":"2018-10-24T09:15:10.000Z","size":123,"stargazers_count":4,"open_issues_count":0,"forks_count":8,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-05T05:05:13.710Z","etag":null,"topics":["archive","siva"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/src-d.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-08-03T11:22:43.000Z","updated_at":"2021-03-18T03:58:21.000Z","dependencies_parsed_at":"2022-09-12T10:11:41.407Z","dependency_job_id":null,"html_url":"https://github.com/src-d/siva-java","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/src-d%2Fsiva-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/src-d%2Fsiva-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/src-d%2Fsiva-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/src-d%2Fsiva-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/src-d","download_url":"https://codeload.github.com/src-d/siva-java/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252442485,"owners_count":21748451,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["archive","siva"],"created_at":"2025-05-05T05:05:19.011Z","updated_at":"2025-05-05T05:05:19.618Z","avatar_url":"https://github.com/src-d.png","language":"Java","readme":"# śiva format शिव for the JVM [![Build Status](https://travis-ci.org/src-d/siva-java.svg?branch=master)](https://travis-ci.org/src-d/siva-java)\n\nThis library is a Java implementation of [siva format](https://github.com/src-d/go-siva/blob/master/SPEC.md).\nIt  is intended to be used with any JVM language.\nThe main implementation is written in Go [here](https://github.com/src-d/go-siva).\n\nThis java library offers an API to read and unpack [siva files](https://github.com/src-d/go-siva/blob/master/SPEC.md) but not to write them yet.\n\n## Usage\n\n`siva-java` is available on [maven central](http://search.maven.org/#search%7Cga%7C1%7Csiva-java). To include it as a dependency in your project managed by [sbt](http://www.scala-sbt.org/) add the dependency to your `build.sbt` file:\n\n```scala\nlibraryDependencies += \"tech.sourced\" % \"siva-java\" % \"[version]\"\n```\n\nOn the other hand, if you use [maven](https://maven.apache.org/) to manage your dependencies, you must add the dependency to your `pom.xml`:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003etech.sourced\u003c/groupId\u003e\n    \u003cartifactId\u003esiva-java\u003c/artifactId\u003e\n    \u003cversion\u003e[version]\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nIf you use [gradle](https://gradle.org) to manage your dependencies, add the following to your `build.gradle` file in the `dependencies` section:\n\n    compile 'tech.sourced:siva-java:[version]'\n\nIn all cases, replace `[version]` with the [latest siva-java version](http://search.maven.org/#search%7Cga%7C1%7Csiva-java).\n\n## Example of Usage\n\n```java\npackage com.github.mcarmonaa.sivaexample;\n\nimport org.apache.commons.io.FileUtils;\nimport tech.sourced.siva.IndexEntry;\nimport tech.sourced.siva.SivaReader;\n\nimport java.io.File;\nimport java.io.InputStream;\nimport java.nio.file.Path;\nimport java.nio.file.Paths;\nimport java.util.List;\nimport java.util.logging.Level;\nimport java.util.logging.Logger;\n\npublic class Main {\n    private static final String SIVA_DIR = \"/tmp/siva-files/\";\n    private static final String SIVA_UNPACKED_DIR = \"/tmp/siva-unpacked/\";\n    private static final String DEFAULT_SIVA_FILE = SIVA_DIR + \"/aac052c42c501abf6aa8c3509424e837bb27e188.siva\";\n    private static final Logger LOGGER = Logger.getLogger(Main.class.getName());\n\n    public static void main(String[] args) {\n        LOGGER.log(Level.INFO, \"unpacking siva-file\");\n        try (SivaReader sivaReader = new SivaReader(new File(DEFAULT_SIVA_FILE))) {\n            List\u003cIndexEntry\u003e index = sivaReader.getIndex().getFilteredIndex().getEntries();\n            for (IndexEntry indexEntry : index) {\n                InputStream entry = sivaReader.getEntry(indexEntry);\n                Path outPath = Paths.get(SIVA_UNPACKED_DIR.concat(indexEntry.getName()));\n                FileUtils.copyInputStreamToFile(entry, new File(outPath.toString()));\n            }\n        } catch (Exception ex) {\n            LOGGER.log(Level.SEVERE, ex.toString(), ex);\n        }\n    }\n}\n```\n\n## Development\n\n### Build\n\nTo build the project and generate a jar file:\n\n    make build\n\nIt leaves the jar file  at `./target/siva-java-[version].jar`, being `[version]` the version specified in the `build.sbt`\n\n### Tests\n\nJust run:\n\n    make test\n\n\n### Clean\n\nTo clean the project:\n\n    make clean\n\n## Limitations\n\nSome known limitations and implementation divergences regarding the [main siva reference specification](https://github.com/src-d/go-siva/blob/master/SPEC.md)\n\nAll the issues commented below are related to the `index` part of the blocks since that is where *siva* really places the metadata. Most of the meta-information is encoded as unsigned values, because of this, most of the problems come from the lack of unsigned values in the `JVM`.\n\nTo avoid these limitations, in some cases, a cast to a bigger number type and a binary `AND` operation with a mask solves the problem. The trick consists of:\n\n```\nunsigned int8 (byte in Go): 255\n\nif you read this byte in Java, it interprets the value as signed. So the same bits in Java result on:\n\nsigned int8 (byte in Java): -1\n\nCasting this value to a java integer, keeps the value as  -1, so we apply a binary mask, with the less weight byte set to all \"ones\" and the rest of the byte to \"zeros\":\n\nbyte b = readByte() // 255 read, but in java the value is -1\nint mask = 0x000000FF\nint n = b \u0026 mask // now n is an integer storing the value 255\n\n```\n\nThis procedure is related on how `JVM` encodes the number values using [two's complement](https://en.wikipedia.org/wiki/Two%27s_complement) and it can apply for all the types which can be cast to a bigger number type.\n\n***Unsigned Integer 64 Limitation!***: a siva file with a value in those fields that the specification encodes as `uint64 ` can contain values in range [0, 2\u003csup\u003e64\u003c/sup\u003e-1] while java implementation only supports values in range [0, 2\u003csup\u003e64-1\u003c/sup\u003e-1]. There's no a number type bigger than a `long` (int64) in java, so this can't be avoided.\n\nNext, are pointed those parts of the `index` affected by different issues:\n\n- Index Signature: [The reference specification](https://github.com/src-d/go-siva/blob/master/SPEC.md) says that a sequence of three bytes (`IBA`) is used as the signature but for the [reference implementation in Go](https://github.com/src-d/go-siva) a byte is an `uint8` while in java a byte is an `int8`. The current java implementation doesn't take care about this since the three bytes used are all of them values less than 127, so these values are read properly.\n\n- Index Entry:\n    - UNIX mode: is encoded as `uint32`, so in java implementation is cast to a long.\n    - The offset of the file content, relative to the beginning of the block: this is an `uint64` value, so the implementation just read it as a long and check that is not negative. ***Unsigned Integer 64 Limitation!***\n    - Size of the file content: encoded as a `uint64`, check no negative. ***Unsigned Integer 64 Limitation!***\n    - CRC32: `uint32` value cast to a `long` java type.\n    - Flags: `uint32` value, it's read without cast type since it only can contain values `0 (No Flags)` or `1 (Deleted)`.\n\n- Index Footer:\n    - Number of entries in the block:  `uint32` value cast to `long` java type.\n    - Index Size in bytes: `uint64` value can't be cast, check no negative. ***Unsigned Integer 64 Limitation!***\n    - Block size in bytes: `uint64`value cant't be cast, check no negative. ***Unsigned Integer 64 Limitation!***\n    - CRC32: `uint32` value cast to a `long` java type.\n\n***Other comments***: This java implementation verify the integrity of the index with the `CRC` in the Index Footer. The integrity of the files should be checked optionally with the `CRC` kept in the Index Entry by the clients of this library.\n\n## License\n\nSee [LICENSE](LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrc-d%2Fsiva-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrc-d%2Fsiva-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrc-d%2Fsiva-java/lists"}