{"id":18554281,"url":"https://github.com/oracle/okafka","last_synced_at":"2025-04-09T23:31:07.800Z","repository":{"id":43193407,"uuid":"258625472","full_name":"oracle/okafka","owner":"oracle","description":"Kafka Java Client for Oracle Transactional Event Queues","archived":false,"fork":false,"pushed_at":"2025-04-08T08:50:56.000Z","size":1296,"stargazers_count":31,"open_issues_count":12,"forks_count":19,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-08T09:34:39.700Z","etag":null,"topics":["aq","converged-database","event-queues","java","kafka","microservices"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oracle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-24T21:12:09.000Z","updated_at":"2025-04-08T08:51:00.000Z","dependencies_parsed_at":"2023-02-16T22:15:27.128Z","dependency_job_id":"19415d79-118e-49cc-84cd-80c29ef7b456","html_url":"https://github.com/oracle/okafka","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fokafka","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fokafka/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fokafka/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oracle%2Fokafka/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oracle","download_url":"https://codeload.github.com/oracle/okafka/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248129608,"owners_count":21052604,"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":["aq","converged-database","event-queues","java","kafka","microservices"],"created_at":"2024-11-06T21:21:03.224Z","updated_at":"2025-04-09T23:31:07.782Z","avatar_url":"https://github.com/oracle.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Kafka Java Client for Oracle Transactional Event Queues\n\n## Building the Kafka Java Client for Oracle TxEventQ distribution\n\nThis distribution contains Java source code to provide Kafka Java client compatibility to Oracle Transactional Event Queues. Some Kafka Java producer and consumer applications can migrate seamlessly to Oracle Transactional Event Queues for scalable event streaming directly built into the Oracle Database.\n\nYou need to have [Gradle 7.3 or above](http://www.gradle.org/installation) and [Java](http://www.oracle.com/technetwork/java/javase/downloads/index.html) installed.\n\nThis distribution contains version 23.4.0.0 of the `Kafka Java Client for Oracle Transactional Event Queues` project. It will be referred as OKafka-23.4.0.0 henceforth. This is tested with JDK 11.0.22, but we recommend using the latest version.\n\nThe Kafka Java Client works with Oracle Database 23ai Free version as well as Oracle Database 23ai available on Oracle Autonomous Cloud platform.\n\nTo test this distribution in free Oracle Cloud environment create [Oracle Cloud account](https://docs.cloud.oracle.com/en-us/iaas/Content/FreeTier/freetier.htm) then create [Oracle Autonomous Transaction Processing Database instance](https://docs.oracle.com/en/cloud/paas/autonomous-data-warehouse-cloud/tutorial-getting-started-autonomous-db/index.html) in cloud.\n\nA database user should be created and should be granted the privileges mentioned in Database user configuration section. Then create a Transactional Event Queue to produce and consume messages.\n\n### Database user configuration\n\nTo run `OKafka application` against Oracle Database, a database user must be created and must be granted below privileges.\n\n```roomsql\ncreate user \u003cuser\u003e identified by \u003cpassword\u003e\n\nGRANT AQ_USER_ROLE to user;\nGRANT CONNECT, RESOURCE, unlimited tablespace to user;\nGRANT EXECUTE on DBMS_AQ to user;\nGRANT EXECUTE on DBMS_AQADM to user;\nGRANT EXECUTE on DBMS_AQIN to user;\nGRANT EXECUTE on DBMS_TEQK to user;\nGRANT SELECT on GV_$SESSION to user;\nGRANT SELECT on V_$SESSION to user;\nGRANT SELECT on GV_$INSTANCE to user;\nGRANT SELECT on GV_$LISTENER_NETWORK to user;\nGRANT SELECT on GV_$PDBS to user;\nGRANT SELECT on USER_QUEUE_PARTITION_ASSIGNMENT_TABLE to user;\nGRANT SELECT on SYS.DBA_RSRC_PLAN_DIRECTIVES to user;\nEXEC DBMS_AQADM.GRANT_PRIV_FOR_RM_PLAN('user');\n```\nFor Oracle database user created on Oracle Autonomous Cloud, below privileges needs to be granted. \n\n```roomsql\nGRANT AQ_USER_ROLE to user;\nGRANT CONNECT, RESOURCE, unlimited tablespace to user;\nGRANT EXECUTE on DBMS_AQ to user;\nGRANT EXECUTE on DBMS_AQADM to user;\nGRANT EXECUTE on DBMS_AQIN to user;\nGRANT EXECUTE on DBMS_TEQK to user;\nGRANT SELECT on GV$SESSION to user;\nGRANT SELECT on V$SESSION to user;\nGRANT SELECT on GV$INSTANCE to user;\nGRANT SELECT on GV$LISTENER_NETWORK to user;\nGRANT SELECT on GV$PDBS to user;\nGRANT SELECT on SYS.DBA_RSRC_PLAN_DIRECTIVES to user;\nEXEC DBMS_AQADM.GRANT_PRIV_FOR_RM_PLAN('user');\n```\n\n\nNote:\nIt is preferred in general to assign or grant a specific quota on a tablespace to a database user instead of granting unlimited quota in default tablespace. One can create a table space and use the following command to grant quota on a specific tablespace to a database user.\n\n```roomsql\nALTER USER user QUOTA  UNLIMITED /* or size-clause */ on tablespace_name;\n```\n\nOnce user is created and above privileges are granted, connect to Oracle Database as this user and create a Topic using below PL/SQL script.\n\n```roomsql\n-- Create an OKafka topic named 'TXEQ' with 5 partition and retention time of 7 days. \nbegin\n    dbms_aqadm.create_database_kafka_topic( topicname=\u003e 'TXEQ', partition_num=\u003e5, retentiontime =\u003e 7*24*3600);\nend;\n```\n\n\u003e Note: A Topic can also be created using OKAFKA Administration methods. Or, through the Producer interface which creates a new topic if it was not previously created.\n\n#### Connection configuration\n\n`OKafka` uses JDBC(thin driver) connection to connect to Oracle Database instance using any one of two security protocols.\n\n1. PLAINTEXT\n2. SSL\n\n1.PLAINTEXT: In this protocol a JDBC connection is setup by providing username and password in plain text in ojdbc.properties file. To use PLAINTEXT protocol user must provide following properties through application.\n\n```text\nsecurity.protocol = \"PLAINTEXT\"\nbootstrap.servers  = \"host:port\"\noracle.service.name = \"name of the service running on the instance\"\noracle.net.tns_admin = \"location of ojdbc.properties file\"  \n```\n\n`ojdbc.properties` file must have below properties\n\n```text\nuser(in lowercase)=DatabaseUserName\npassword(in lowercase)=Password\n```\n\n2.SSL: This protocol requires that, while connecting to Oracle Database, the JDBC driver authenticates database user using Oracle Wallet or Java KeyStore(JKS) files. This protocol is typically used to o connect to Oracle database 23ai instance in Oracle Autonomous cloud. To use this protocol `Okafka` application must specify following properties.\n\n```text\nsecurity.protocol = \"SSL\"\noracle.net.tns_admin = \"location containing Oracle Wallet, tnsname.ora and ojdbc.properties file\"\ntns.alias = \"alias of connection string in tnsnames.ora\"\n```\n\nDirectory location provided in `oracle.net.tns_admin` property should have:\n\n1. Oracle Wallet\n2. tnsnames.ora file\n3. ojdbc.properties file (optional) \nThis depends on how the Oracle Wallet is configured.\n\nLearn more about [JDBC Thin Connections with a Wallet (mTLS)](https://docs.oracle.com/en/cloud/paas/atp-cloud/atpug/connect-jdbc-thin-wallet.html#GUID-5ED3C08C-1A84-4E5A-B07A-A5114951AA9E) to establish secured JDBC connections.\n\n\u003e Note: tnsnames.ora file in wallet downloaded from Oracle Autonomous Database contains JDBC connection string which is used for establishing JDBC connection.\n\n#### APIs configuration\n\nYou can get a detailed description of the Producer, Consumer and Administration APIs in the [Kafka APIs for Oracle Transactional Event Queues Documentation](https://docs.oracle.com/en/database/oracle/oracle-database/23/adque/Kafka_cient_interface_TEQ.html#GUID-5549915E-6509-4065-B05E-E96338F4742C).\n\n\u003e Note: Topic name property should be provided in UPPERCASE.\n\u003e\n\u003e\u003e ```text\n\u003e\u003e topic.name=\u003cOracle Database TxEventQ Topic, use uppercase\u003e\n\u003e\u003e ```\n\n### Building okafka.jar\n\nSimplest way to build the `okafka.jar` file is by using Gradle build tool.\nThis distribution contains gradle build files which will work for Gradle 7.3 or higher.\n\n```shell\n./gradle jar\n```\n\nThis generates `okafka-23.4.0.0.jar` in `okafka_source_dir/clients/build/libs`.\n\n**Project Dependency:**\n\nMandatory jar files for this project to work.\n\n* `ojdbc11-\u003cversion\u003e.jar`\n* `aqapi-\u003cversion\u003e.jar`\n* `oraclepki-\u003cversion\u003e.jar`\n* `osdt_core-\u003cversion\u003e.jar`\n* `osdt_cert-\u003cversion\u003e.jar`\n* `javax.jms-api-\u003cversion\u003e.jar`\n* `jta-\u003cversion\u003e.jar`\n* `slf4j-api-\u003cversion\u003e.jar`\n* `kafka-clients-3.7.1.jar`\n\nAll these jars are downloaded from Maven Repository during gradle build.\n\nTo build the `okafka.jar` file which includes all the dependent jar files in itself.\n\n```shell\n./gradle fullJar \n```\n\nThis genddsferates `okafka-full-23.4.0.0.jar` in `okafka_source_dir/clients/build/libs`.\n\n## Build javadoc\n\nThis command generates javadoc in `okafka_source_dir/clients/build/docs/javadoc`\n\n```shell\ngradle javadoc\n```\n\n## Examples\n\nRepository contains 2 common OKafka application examples in `examples` folder.\n\n`1. ProducerOKafka.java`\nProduces 10 messages into TxEQ topic.\n\n`2. ConsumerOKafka.java`\nConsumes 10 messages from TxEQ topic.\n\n## Kafka Java Client APIs supported\n\nFor detailed documentation of OKafka please refer to [Kafka API for Oracle Transactional Event Queues](https://docs.oracle.com/en/database/oracle/oracle-database/23/adque/Kafka_cient_interface_TEQ.html) documentation.\n\nFor list of APIs supported with Oracle 23.4.0.0 version of OKafka please refer to [OKafka 23ai javadoc](https://docs.oracle.com/en/database/oracle/oracle-database/23/okjdc/). \n\n## Contributing\n\nThis project is not accepting external contributions at this time. For bugs or enhancement requests, please file a GitHub issue unless it’s security related. When filing a bug remember that the better written the bug is, the more likely it is to be fixed. If you think you’ve found a security vulnerability, do not raise a GitHub issue and follow the instructions in our [security policy](./SECURITY.md).\n\n## Security\n\nPlease consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process\n\n## License\n\nCopyright (c) 2019, 2024 Oracle and/or its affiliates.\n\nReleased under the Universal Permissive License v1.0 as shown at\n\u003chttps://oss.oracle.com/licenses/upl/\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foracle%2Fokafka","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foracle%2Fokafka","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foracle%2Fokafka/lists"}